Bitfield Docs

When a Runtime Kit feature breaks, do not guess. Identify which public link failed: package file, named data read, target request, reply decoding, local state, or activation.

What this is

Runtime Kit deliberately hides private implementation details from app code. That is good for product architecture, but it means debugging should follow the public chain instead of poking unpublished code.Use this chain:

package file
  -> package admission
  -> named data read input
  -> React surface
  -> target request
  -> reply decoding
  -> local state and activation

Name what the user sees, not what you assume broke.

Pick boundary, read, request, reply, local state, or activation.

Capture the safe name, payload shape, state, or error.

Fix one link and prove the expected state appears.

Do not skip straight to private files. First prove which public link failed.

Start with the symptom

Symptom	Most likely link	First evidence to capture
Package never becomes available.	Package file or package admission.	Package name, package set, boundary filename, boundary JSON error.
Component stays empty.	Named data read input.	Input name, component states, whether `data === null`.
Component throws immediately.	Missing read scope or unavailable input.	Exact error message and component location.
Button call throws before work runs.	Target request shape.	Target name and payload shape.
Button call succeeds but UI cannot use the result.	Reply decoding.	Reply byte format and decoder code.
Works on one device but not another.	Activation or package set/local state.	Device scope and account activation state.
App code imports deep Runtime Kit files.	App boundary violation.	Import list and files changed.

Find the link first. Then fix that link.

First five minutes

Do this before editing code:

Minute	Action	What you learn
1	Write the package set, package name, prepared input, and target name.	Whether everyone is debugging the same feature.
2	Check the package file exists and names the record or slot.	Whether the package can be admitted.
3	Check the component renders loading, error, empty, and success.	Whether the UI is hiding the real state.
4	Check the request payload and reply decoder.	Whether the button and target agree on a contract.
5	Check whether the issue is one device or every device.	Whether activation/local state is involved.

If you cannot fill in the contract, that is the bug. Write the contract first, then debug the link that does not match it.

## Runtime Kit contract

- Package set:
- Package:
- Prepared input:
- Target:
- Request payload:
- Reply payload:
- Device scope: one device or every device

Package file failures

Check the boundary file before blaming React.Valid packages have one boundary file:

things-to-store-and-run.json

The package should declare supported thing types:

Thing type	Common failure
`record`	The record has no payload action or multiple payload actions.
`stored_bytes`	The file path does not stay inside the package.
`slot`	The slot has no boundary or no method list.

Fix package file problems in the package. Do not work around them in the app surface.Fast boundary checklist:

folder exists
boundary file is named things-to-store-and-run.json
JSON parses
top-level package field is non-empty
things is an array
each thing has a supported type
package-owned paths stay inside the package folder

Verify the fix:

Fix	Verification
Add missing boundary file.	The package folder contains `things-to-store-and-run.json`.
Fix unknown thing type.	The boundary uses only supported public thing types.
Fix escaped file path.	Every package-owned file path stays inside the package.
Fix missing slot boundary.	The slot declares its public call shape and methods.

Named data read failures

If useBitfieldData(...) does not return the value you expected, check the input name and surface contract.

const welcome = useBitfieldData<WelcomeCopy>('welcome-copy');

Ask:

Question	Why it matters
Is `welcome-copy` the public input name for this surface?	Selector names are not storage paths.
Does the component render `loading`?	The value may not be ready yet.
Does the component render `error`?	A hidden thrown error becomes a bad user experience.
Does the component handle `data === null`?	Empty is a real state.
Did app code import only the public React hook?	Deep imports bypass the boundary.

The correct fix is usually to repair the package/surface contract or the component states, not to create a private read path.Read failures split into two different problems:

Problem	What it looks like	Correct fix
The input is not available.	Loading never resolves or Runtime Kit reports unavailable input.	Fix the package/surface contract that prepares the input.
The UI hides the state.	The hook returns loading, error, or null but the component renders nothing helpful.	Render all states visibly.

Do not solve either problem by reading local files from the component. That creates a second data path and hides the real broken link.Verify the fix:

The component shows loading while waiting.
The component shows a visible error when Runtime Kit reports one.
The component shows an empty state when data is null.
The component renders real data when the prepared input is available.

Missing read scope errors

If you see an error like:

useBitfieldData() without an input handle requires a Bitfield read scope

The component is trying to read a prepared input without the app surface that provides it.Do not fix this by importing private provider or scope code into the component. The surface owner must provide the read scope before the component renders, or the component must receive an input handle through the public shape that surface supports.

Target request failures

The request function needs a non-empty public action name.

await sendRequestToBitfieldTarget({
  target: 'welcome.suggest',
  payload: { topic: 'launch' },
});

Check:

Question	Why it matters
Is `target` a non-empty string?	Runtime Kit rejects empty target names.
Does the package declare that target?	App code can only call public doors.
Is the payload shape what the target expects?	Runtime Kit sends bytes; the target owns meaning.
Should this request be cancellable?	Search, typeahead, and long work should use `AbortController`.

Do not import the target implementation to “make the button work.” That bypasses Runtime Kit.Request failures split into four common cases:

Case	What to check	Fix
Empty target	`target` is missing or `''`.	Pass the public action name declared by the package.
Unknown target	The package does not declare that door.	Add or fix the `slot` declaration in the package file.
Bad payload	The target expects another shape.	Update the caller or action reply shape, then document the chosen shape.
Stale request	Old work returns after newer user input.	Use `AbortController` when stale work matters.

Verify the fix:

Check	Pass condition
Target name	Non-empty string and declared by the package.
Payload	Matches the public action reply shape.
Abort behavior	Search, typeahead, and long work use an abort signal when stale work matters.
App boundary	Button imports `sendRequestToBitfieldTarget(...)`, not target implementation code.

Reply decoding failures

The reply is bytes:

const reply = await sendRequestToBitfieldTarget({
  target: 'welcome.suggest',
  payload: { topic: 'launch' },
});

Decode according to the action reply shape:

const text = new TextDecoder().decode(reply.payload);
const data = JSON.parse(text);

If JSON parsing fails, the request may still have succeeded. The problem may be that the target returned text, binary bytes, an error payload, or a different JSON shape than the app expected.Write the reply shape beside the caller:

type SuggestionReply = {
  suggestion: string;
};

Then decode to that contract only after the target promises JSON:

const text = new TextDecoder().decode(reply.payload);
const data = JSON.parse(text) as SuggestionReply;

If the target returns binary data, do not force it through JSON. Keep the reply as bytes and document the binary format.Debug reply failures with this order:

Decode the bytes as text only if the target promises text or JSON.
Parse JSON only if the target promises JSON.
Check whether the reply is an error payload with a different shape.
Check whether the target changed its public reply shape.
Update either the action reply shape or the decoder, not both blindly.

Payload conversion surprises

Runtime Kit converts payloads before sending:

Payload	Sent as
`Uint8Array`	The same bytes.
`string`	Text bytes.
object, array, number, or boolean	JSON bytes.
`null` or omitted	Empty bytes.

That last row is easy to miss. If your target needs a JSON null, send an object with an explicit field instead, such as { "value": null }.

A record reads back empty even though you just wrote it

A record’s address mode is part of its identity. Read it the same way it was written, or the engine will not find it — even though the bytes are present.

Address shape	Stored as
`package::thing::name` (a `::` scheme)	label-hash
`partition\|thing\|name` (contains `\|`)	identity-text

A workflow write step that targets a :: address with no explicit address mode stores it label-hash. If a reader (or a producer poll) looks for that address in identity-text mode, it gets “not found” forever. When a value “won’t read back,” read it at both modes to discover which one the writer used, then make the reader match.

Symptom: write succeeds, read returns empty/not-found.
Check: did the writer use a `::` address (label-hash) and the reader poll identity-text (or vice-versa)?
Fix: make the reader's address mode match the writer's.

Removing a placeable-surface (or any current-state record) from things-to-store-and-run.json and redeploying with the live-log-only path does not remove it from the running app. That deploy is additive — it writes the records present in your source; it never retracts records you deleted from source.To retract an already-admitted record, add an explicit tombstone to your source and redeploy:

{
  "type": "record",
  "address": "package::your-package::placeable-surface::old-surface",
  "address_mode": "identity_text",
  "path": ["current-item", "published-record"],
  "remove": true
}

The deploy then emits a removal for that exact address. Verify the record is gone by reading the address directly (it should report not-found). Keep the tombstone in source — it is the durable record that this address is retired.

A loading card (AI producer) is stuck “Working…” forever

A board/producer surface dispatches an action, then polls a result address to know when it is done. If the poll’s address mode does not match where the action actually wrote its result, the surface never sees the result and shows its loading copy forever — even though the action finished successfully and wrote a real record.

Symptom: producer card spins on "Working…" indefinitely; the action actually completed.
Check: read the producer's result address at both address modes.
Fix: set the producer's poll address mode to the one that returns the record.

This is the same root cause as “reads back empty”: the result was written one way and read another. It is not a stuck engine.

Local state confusion

Customer-visible Bitfield state lives under:

~/.bitfield/
  stored-data/
  runtime-kit/
  check-license/

Use this meaning:

Area	Debug meaning
`stored-data/`	Durable Bitfield data area. Do not edit by hand.
`runtime-kit/`	Package sets and current Runtime Kit process state.
`check-license/`	Device permission material. Use account flows for activation issues.

Do not copy one device’s local state to another device as a fix. Device permission and package state need the right owner flow.Safe support note:

It is OK to say which top-level area seems involved: stored-data, runtime-kit, or check-license.
Do not paste file contents from those folders into public channels.
Do not copy those folders between devices.

Boundary failures

Check for these violations before debugging private files:

Violation	Fix
Imports from unpublished Runtime Kit paths.	Replace with public imports only.
React component parses package files.	Move package material to the boundary and read named data.
Button imports target implementation.	Call `sendRequestToBitfieldTarget(...)`.
Component ignores loading/error/empty.	Add all four states.
Target reply is parsed without a contract.	Decode according to the target’s public reply shape.

Code tends to connect things directly when the boundary is not repeated clearly. Use Build with AI agents only when the feature is being generated by an AI agent.Use this note when a change crosses the Runtime Kit boundary:

This crosses the Runtime Kit boundary. Keep app code on public imports only.
Name the prepared input or target instead of importing package implementation code.
Show loading, error, empty, success, and request-result states.

Escalation checklist

Before asking for support, capture the public facts:

The package name.
The package set name.
The public input name that failed.
The public action name that failed.
The payload shape, without secrets or customer data.
The visible error message.
Whether the problem happens on one device or every device.

Do not paste local state contents, device permission files, private keys, tokens, or customer data into public support channels.

Quick reference

No data       -> check prepared input and render states
Request fails -> check target name and payload shape
Decode fails  -> check reply shape
Device differs -> check activation and package set
Boundary crossed -> remove private imports and direct implementation calls

Now build the bigger version

Add a small public debug note beside every Runtime Kit feature.

## Runtime Kit contract

- Package set: customer-portal
- Package: launch-assistant
- Prepared inputs: welcome-copy, launch-checklist
- Targets: launch.next-step
- Request shape: { currentStep: string }
- Reply shape: { nextStep: string; reason: string }

When something breaks, compare the bug to that contract. If the prepared input is missing, fix the package/surface link. If the target reply has a different shape, fix the action reply shape or the decoder. If one device behaves differently, check activation and package-set state before touching the UI.That gives support and developers the same map without exposing local state contents or private implementation files.

Use Runtime Kit

Understand Runtime Kit

Build without tangled code

Runtime Kit Cookbook

Reference

Troubleshooting

What this is

Start with the symptom

First five minutes

Package file failures

Named data read failures

Missing read scope errors

Target request failures

Reply decoding failures

Payload conversion surprises

A record reads back empty even though you just wrote it

A surface I removed still shows in the sidebar

A loading card (AI producer) is stuck “Working…” forever

Local state confusion

Boundary failures

Escalation checklist

Quick reference

Now build the bigger version

​What this is

​Start with the symptom

​First five minutes

​Package file failures

​Named data read failures

​Missing read scope errors

​Target request failures

​Reply decoding failures

​Payload conversion surprises

​A record reads back empty even though you just wrote it

​A surface I removed still shows in the sidebar

​A loading card (AI producer) is stuck “Working…” forever

​Local state confusion

​Boundary failures

​Escalation checklist

​Quick reference

​Now build the bigger version

What this is

Start with the symptom

First five minutes

Package file failures

Named data read failures

Missing read scope errors

Target request failures

Reply decoding failures

Payload conversion surprises

A record reads back empty even though you just wrote it

A surface I removed still shows in the sidebar

A loading card (AI producer) is stuck “Working…” forever

Local state confusion

Boundary failures

Escalation checklist

Quick reference

Now build the bigger version