Bitfield Docs

things-to-store-and-run.json is the package file Runtime Kit checks. It lists the records, package-owned files, and callable actions the package brings.

Use this page when you need exact field rules. If you want to copy a working file, use Package set with one record, Package-owned file, or Callable package slot.

File location

<package-name>/
  things-to-store-and-run.json

Runtime Kit reads this file from the package folder. Other package files only matter when things-to-store-and-run.json refers to them through package-local paths such as source_path.

Minimum file

{
  "package": "sample-package",
  "things": []
}

Field	Type	Required	Constraints	Meaning
`package`	string	yes	Must name the package whose folder owns this file.	Separates package-owned records, bytes, and actions.
`things`	array	yes	Each item must be a supported thing type.	Declares records, stored bytes, and slots.

Unknown top-level fields may be rejected. The public machine-readable schema is reference/package-boundary.schema.json, and Runtime Kit Cookbook examples are kept aligned with it.

Thing type overview

Thing type	Required fields	Public result	Use this recipe
`record`	`type`, `address`, one payload action	One package-owned durable record is admitted.	Package set with one record
`stored_bytes`	`type`, `name`, `source_path`	Package-owned bytes are stored under a package-owned name.	Package-owned file
`slot`	`type`, `name`, `methods`, `boundary`, artifact or build data	One callable action is admitted.	Callable package slot

Unknown thing types are rejected before they become active.

`record`

{
  "type": "record",
  "address": "package::sample-package::main",
  "payload": { "ready": true }
}

Field	Type	Required	Constraints	Meaning
`type`	string	yes	Must be `"record"`.	Selects the record thing shape.
`address`	string	yes	Should be a package-owned public address.	Names the durable record.
`payload`	JSON value	one payload action required	Mutually exclusive with `payload_text`, `payload_base64`, and `remove`.	Stores a JSON payload.
`payload_text`	string	one payload action required	Mutually exclusive with other payload actions.	Stores text bytes.
`payload_base64`	string	one payload action required	Mutually exclusive with other payload actions.	Stores decoded bytes from base64 text.
`remove`	boolean	one payload action required	Use `true`; mutually exclusive with payload fields.	Retracts/removes the record.

Valid text record:

{
  "type": "record",
  "address": "package::sample-package::intro",
  "payload_text": "Welcome to the product."
}

Invalid record:

{
  "type": "record",
  "address": "package::sample-package::intro",
  "payload": { "title": "Welcome" },
  "payload_text": "Welcome"
}

This is invalid because a record must choose exactly one payload action.

`stored_bytes`

{
  "type": "stored_bytes",
  "name": "help/getting-started.txt",
  "source_path": "help/getting-started.txt"
}

Field	Type	Required	Constraints	Meaning
`type`	string	yes	Must be `"stored_bytes"`.	Selects the stored-bytes thing shape.
`name`	string	yes	Package-owned public name.	Final package-owned byte name.
`source_path`	string	yes	Must resolve inside the package folder.	File to read from the submitted package.

Valid package-owned file:

{
  "type": "stored_bytes",
  "name": "help/getting-started.txt",
  "source_path": "help/getting-started.txt"
}

Invalid package-owned file:

{
  "type": "stored_bytes",
  "name": "secret.txt",
  "source_path": "../secret.txt"
}

This is invalid because source_path escapes the package folder. A package can only bring files it owns.

`slot`

{
  "type": "slot",
  "name": "help.search",
  "methods": [{ "name": "query" }],
  "boundary": {
    "call_shape": "envelope-bytes-in-envelope-bytes-out",
    "methods": [{ "name": "query" }]
  },
  "artifact": {
    "source_path": "slots/help-search.bin"
  }
}

Field	Type	Required	Constraints	Meaning
`type`	string	yes	Must be `"slot"`.	Selects the package item that app code can ask to do work.
`name`	string	yes	Public action name.	The name app code calls through `sendRequestToBitfieldTarget(...)`.
`methods`	array of method objects	yes	Must list public methods, usually `{ "name": "query" }`.	Declares the package’s callable method names.
`boundary`	object	yes	Must include `call_shape` and matching public methods.	Describes what bytes the callable action receives and returns.
`boundary.call_shape`	string	yes	Public recipes use `"envelope-bytes-in-envelope-bytes-out"`.	States that the action receives bytes and returns bytes.
`boundary.methods`	array of method objects	yes	Should match `methods`.	Repeats the public methods for the callable action.
`artifact.source_path`	string	artifact path choice	Must resolve inside the package folder.	Prebuilt package-owned bytes for the callable action.

Valid slot:

{
  "type": "slot",
  "name": "launch.next-step",
  "methods": [{ "name": "query" }],
  "boundary": {
    "call_shape": "envelope-bytes-in-envelope-bytes-out",
    "methods": [{ "name": "query" }]
  },
  "artifact": {
    "source_path": "slots/next-step.bin"
  }
}

Invalid slot:

{
  "type": "slot",
  "name": "launch.next-step",
  "methods": [],
  "boundary": {
    "call_shape": "envelope-bytes-in-envelope-bytes-out",
    "methods": [{ "name": "query" }]
  },
  "artifact": {
    "source_path": "../next-step.bin"
  }
}

This is invalid for two public reasons: the public method list is empty, and the artifact path escapes the package folder.

Complete valid package file

{
  "package": "launch-product",
  "things": [
    {
      "type": "record",
      "address": "package::launch-product::welcome-copy",
      "payload": {
        "headline": "Your launch stays fast.",
        "body": "Every feature keeps its package data and callable actions listed in one package file."
      }
    },
    {
      "type": "stored_bytes",
      "name": "help/getting-started.txt",
      "source_path": "help/getting-started.txt"
    },
    {
      "type": "slot",
      "name": "help.search",
      "methods": [{ "name": "query" }],
      "boundary": {
        "call_shape": "envelope-bytes-in-envelope-bytes-out",
        "methods": [{ "name": "query" }]
      },
      "artifact": {
        "source_path": "slots/help-search.bin"
      }
    }
  ]
}

This file is valid because every declared item is package-owned, each path stays inside the package folder, and the callable action has a public name plus bytes-in/bytes-out call details.

Common failures

Symptom	Cause	Fix
Package admission rejects the file immediately.	Missing top-level `package` or `things`.	Add both fields, even when `things` is empty.
Record cannot be admitted.	The record picked zero or more than one payload action.	Use exactly one of `payload`, `payload_text`, `payload_base64`, or `remove: true`.
Stored bytes cannot be found.	`source_path` does not exist inside the package folder.	Put the file inside the package and point `source_path` to that package-local path.
Stored bytes or slot artifact is rejected.	The path escapes the package folder.	Remove `../` and absolute paths. A package cannot claim outside files.
App code cannot call the action.	Slot `name`, `methods`, and `boundary.methods` do not describe the callable action clearly.	Use a stable action name and include `{ "name": "query" }` in both method lists when the recipe is query-shaped.

What app code may rely on

Public package file may say	App code should not depend on
Package name, record address, stored byte name, package-local source path, action name, method names.	Local absolute paths, private runner setup, hidden build machines, package compiler implementation details.
Payload shape owned by your package.	Runtime Kit internal storage layout.
Callable action details: bytes in, bytes out.	How the action implementation is wired internally.

Need	Page
First package file	Package set with one record
Package-owned bytes	Package-owned file
Callable target	Callable package slot
App request API	Runtime Kit API
Package guide	Packages

​File location

​Minimum file

​Thing type overview

​record

​stored_bytes

​slot

​Complete valid package file

​Common failures

​What app code may rely on

​Related pages