Bytecode & cross-platform delivery¶

The source is for people. DBC is the promise machines agree to keep.

A .bas file describes a program in D/BASIC. The compiler turns it into a .dbc executable image whose types, instructions, capabilities, limits, faces, and dependencies are explicit enough for very different runtimes to agree about it.

The artifact family¶

Extension	Meaning	Contains
`.bas`	D/BASIC source	human-readable program and imports
`.dbc`	D/BASIC executable bytecode	validated code, constants, type metadata, static layout, faces, requirements
`.dbl`	shared D/BASIC library	DBC code plus identity/versioned export surface, no application face
`.dpk`	D/OS package	manifest, digests, signature, executable/library/assets, associations
`.dmd`	native D/OS module envelope	trusted runtime descriptor; not native-compiled D/BASIC

The distinction prevents a common deployment confusion: .dbc is the portable program. .dpk is how that program and its dependencies are distributed and trusted. .dmd describes a different native module route; it is not what the compiler secretly produces on one favored platform.

Build once¶

dbasic build postcard.bas -o postcard.dbc

Run the result without recompiling:

dbasic exec postcard.dbc

Or compile and run in one step:

dbasic run postcard.bas

run and trace inspect the input's magic bytes rather than trusting its filename, so renaming source to .dbc cannot trick the loader into executing text.

One image, several homes¶

                         ┌─ browser WebAssembly runner → WebGL2 composed scene
postcard.bas → postcard.dbc ─┼─ Windows runner → native window / console
                         ├─ Linux runner   → native window / console
                         ├─ macOS runner   → native window / console
                         └─ D/OS runtime   → composed product head

The optimizing compiler and console runner build on Windows, Linux, and macOS. The browser compiles and executes through WebAssembly. Native presentation uses the same DBC/runtime boundary. D/OS consumes the same instruction and Intent vocabulary through its local runtime and composed head.

This is not source compatibility in the weak sense of “recompile several similar programs.” DBC gives the runners one artifact and one observable contract.

Portability is not the lowest common denominator¶

Every application declares a coarse maximum capability promise, and the compiler records the exact reachable vocabulary inside that boundary. A rich runner can upgrade how those meanings are performed; a small runner can lower them to simpler routes. If a destination cannot admit the declared application promise or the emitted version floor, it refuses before execution rather than changing the program.

That means you can write a program that requires styled text or DATA persistence without forcing every tiny target to pretend it offers those things. The same image runs where its declared contract is admitted.

Read Intents & Services for font, color, math, graphics, and bulk-operation adaptation.

What is inside a DBC image¶

DBC begins with a fixed 64-byte little-endian header. It identifies and bounds:

code bytes;
constant/type pool bytes;
static storage;
runtime memory requirements;
total image length;
face table and entry points;
value-stack and call-frame ceilings;
feature/version requirements; and
dependency and library flags.

The loader validates every range before execution. An image may be larger than one resident 64 KiB window because runtimes page immutable image data through governed handles; the bytecode contract is not the address space of one vintage CPU. The 6502 large-memory model starts with a 512 KiB target profile while keeping banking out of application source.

Parse, bind, admit, execute¶

open bytes → validate DBC → bind exact .dbl dependencies → admit versions/capabilities → execute in slices → present/refuse/halt

1. Validate¶

The container checks magic, length, versions, sections, instruction boundaries, types, stack effects, faces, and metadata. Malformed data does not become a half-running program.

2. Bind¶

If the image imports shared libraries, the loader resolves each exact identity, version, signature, class shape, and SHA-256 digest. Binding finishes before program code runs.

3. Admit¶

The host compares the image's Service, Intent, MATH, memory, and presentation needs with routes it actually provides.

4. Execute in bounded turns¶

The VM runs a finite instruction slice, then yields a terminal halt/refusal, a pending external operation, a lifecycle boundary, or more runnable work. This keeps a browser UI and a small D/OS machine responsive without introducing different language semantics.

5. Complete visibly¶

A frame is complete at its presentation receipt, not merely when a GPU queue accepts it. An external commit is complete at its receipt, not merely when the application asks. D/BASIC names these boundaries so runners cannot disagree quietly.

Versioning¶

The DBC version has independent container and Service components. An old-only program can declare an older minimum even when built by a newer compiler; the compiler raises only the components required by emitted features.

This reference was audited against DBC 1.15.1.10 on 2026-09-02. Selected feature floors illustrate the model:

Feature	Minimum DBC
records	`1.1.1.0`
objects	`1.3.1.0`
portable math evaluation batches	`1.4.1.0`
extended window lifecycle faces	`1.8.1.0`
dependent program images	`1.9.1.10`
`ARRAYCOPY`	`1.10.1.0`
library artifacts	`1.11.1.10`
cross-artifact calls	`1.12.1.10`
typed array signatures	`1.13.1.10`
`ARRAYFILL` and `ARRAYSWAP`	`1.14.1.0`
shared class descriptors	`1.15.1.10`

A newer runtime can admit an older declared floor. An older runtime rejects a future requirement by version before encountering an unknown opcode.

Cross-platform runners¶

Destination	Same invariant	Local adaptation
browser	DBC validation, sliced VM, normalized window/input, GFX Intents	worker execution, retained WebGL2 scene, browser-font textures
Windows	compiler/runtime/Service/Intent contracts	native event loop, WGPU presentation, local providers
Linux	compiler/runtime/Service/Intent contracts	native event loop, WGPU presentation, Linux providers
macOS	compiler/runtime/Service/Intent contracts	native event loop, WGPU presentation, macOS providers
D/OS	bytecode, requirements, faces, handles, Intents	product compositor, hardware/provider routes, bounded paging

Application source contains no platform cfg, host path, native pointer, windowing toolkit object, or conditional dialect. A runner owns those adaptations.

Shared libraries travel by identity¶

IMPORT dworks.widgets SHARED

The compiler emits a dependency only for a used export. The package installs the exact .dbl; the loader binds it before execution. A virtual call into an imported class still follows one class identity and dispatch model across the artifact boundary.

For a self-contained delivery, use BAKED. See Imports & Libraries.

Packages and trust¶

A D/OS package binds distribution facts the BASIC source should not own:

application identity and version;
.dbc, .dbl, and asset membership;
SHA-256 digests;
file associations such as .dbc execute and .bas edit;
capability/product policy; and
publisher signature.

Signature verification establishes publisher/package trust at install. Digest verification ensures the artifact opened at launch is the artifact the manifest named. DBC validation still checks structural safety; each layer answers a different question.

A practical delivery loop¶

Write and test .bas in the playground or desktop tool.
Run representative success and refusal cases.
Build one .dbc.
Execute that exact image on each intended runner.
Compare canonical traces where runtime equivalence matters.
Package the exact image and required .dbl/asset bytes.
Verify the package, then test install and launch admission.

Do not recompile independently on each target unless you are testing the compiler itself. Shipping one byte-exact DBC is how you know the platforms received the same program.

The cross-platform habits¶

Store meaning in values, records, objects, and handles—not addresses.
Let RESIZE drive layout.
Use widgets and semantic font/color roles.
Use Intents for external work.
State bulk work with bulk verbs.
Keep optional capability recovery explicit.
Test the artifact, not merely the source build.

Next: Compatibility, Migration & Refusals →