carried

Carried mounts: content of another world, mounted read-only for this session at /zero/runtime/carried/<key>/ without installing it. A closure is named by the address of its manifest (closureSha, the sha-256 ZeroMind serves the manifest at); the engine reads the manifest and every file it names through the device's content cache, lays the files out the way their world places them, and states where the mount stands in <key>/status. Nothing a mount holds is content of the open world: it is in no listing of its assets, no dependency table, no push and no zm status, and the open world's code cannot require from it. A mount lives while some caller holds it and the session lasts.

carried.mount(closureSha, { key = "ada.avatar" }) holds a mount and starts filling it; carried.wait(key) yields until it settles; carried.status(key) reads where it stands; carried.release(key) lets go of it. carried.mountDraft(assetPath) mounts the closure of an asset of the open world's working tree the same way, for a preview on this engine. carried.resolve(key, reference) answers what a reference written inside the closure names. guides { path: "core/carried" } covers the whole surface.

require("@builtin::modules.api.engine.carried") -- carried (also available as global 'carried')

The carried namespace: 27 functions.

globals/carried/heldBytes

carried.heldBytes() -> number

The bytes every carried mount holds in this engine's memory.

Returns number — Bytes.

print(carried.heldBytes())

globals/carried/list

carried.list() -> { Status }

The status of every carried mount of this session.

Returns { Status } — One status per mount.

for _, m in carried.list() do print(m.key, m.state) end

globals/carried/manifest

carried.manifest(key: string) -> string?

The manifest of the ready mount at key: the JSON bytes the content store served ($schema zero/closure/v1, root, and entries, one per file and folder with its world path, asset_guid, checksum, size_bytes, kind and origin, plus one engine entry per builtin it was built against). Their sha-256 is the mount's closureSha. Nil until the mount is ready.

Parameters

• key string — The mount's key.

Returns string? — The manifest's bytes, or nil.

local entries = require("@builtin::modules.json").decode(carried.manifest("ada.avatar")).entries

globals/carried/mount

carried.mount(closureSha: string, options: MountOptions?) -> Status

Hold the carried mount of the closure whose manifest address is closureSha and start filling it, unless it is already held. The mount stands at /zero/runtime/carried/<key>/; a key holds one closure for as long as anyone uses it, and every mount of the same closure at the same key holds it once more. Answers at once with the mount's status (state resolving while it fills); carried.wait yields until it settles. Raises when the key is malformed, closureSha is no sha-256, or the key holds another closure.

Parameters

• closureSha string — The sha-256 hex digest of the closure's manifest.
• options MountOptions (optional) — key: the mount's folder name (one path segment of letters, digits, ., _, -), default closure-<first 16 hex digits>; commit: the commit the closure was published at, stated in the status.

Returns Status — The mount's status.

local m = carried.mount(sha, { key = "ada.avatar" }); local s = carried.wait(m.key)

globals/carried/mountDraft

carried.mountDraft(assetPath: string, options: MountOptions?) -> Status

Hold a draft carried mount of the asset at assetPath, an asset of the open world's working tree (or of your home folder): the engine walks the asset and every asset its files reference, writes that closure and its manifest into the device's content cache, and mounts it from there the way a published closure mounts, labelled draft = true. It is this engine's alone. Mounting it again rebuilds it from the tree as it stands. A draft holding a home folder's content is that folder's: it is made for code that reaches the folder, and its files, listing, status and manifest answer that code alone. Raises, naming the folder, when the asset or anything it reaches is in a home folder the calling code does not reach.

Parameters

• assetPath string — The asset, e.g. /zero/source/chars/ada.avatar.
• options MountOptions (optional) — key: the mount's folder name, default draft-<asset name>.

Returns Status — The mount's status.

local d = carried.mountDraft("/zero/source/props/lamp.model"); carried.wait(d.key)

globals/carried/release

carried.release(key: string) -> number

Let one holder of the mount at key go. The last one takes it down: its folder leaves /zero/runtime/carried/ and its bytes leave this engine's memory, while the device's content cache keeps them for the next mount. Raises when no mount is held at key.

Parameters

• key string — The mount's key.

Returns number — How many holders still hold it.

carried.release("ada.avatar")

globals/carried/resolve

carried.resolve(key: string, reference: string) -> string?

What reference, written by content of the closure at key, names: a guid the closure carries, a path of its world (props/lamp.model, /zero/source/props/lamp.model) or an identity of its world (props.lamp) answers the file inside the mount; a reference to the engine library answers the library asset, taken to the version of an engine builtin the closure was built against when the mount holds that version. The open world's own content answers none of it. Nil when nothing answers.

Parameters

• key string — The mount's key.
• reference string — A guid, path, identity or library reference.

Returns string? — A VFS path, or nil.

local tex = carried.resolve("ada.avatar", "chars.ada_albedo")

globals/carried/status

carried.status(key: string) -> Status?

Where the mount at key stands, as <key>/status states it: state is resolving, fetching, measuring, ready, refused or none; reason is a word saying why nothing is mounted (unreachable, notFound, incomplete) or why the closure was refused, with detail the sentence; bytesFetched / bytesTotal count the files read; measured counts files, folders and bytes per kind once ready; builtin names how each engine builtin the closure was built against resolves (host, mount, or hostOtherVersion with why). Nil when no mount is held at key, and when the mount holds a home folder's content the calling code does not reach.

Parameters

• key string — The mount's key.

Returns Status? — The status, or nil.

print(carried.status("ada.avatar").state)

globals/carried/wait

carried.wait(key: string, seconds: number?) -> Status

Yield until the mount at key settles (ready, refused or none) or seconds pass, and answer its status then. Raises when no mount is held at key, or when it holds a home folder's content the calling code does not reach.

Parameters

• key string — The mount's key.
• seconds number (optional) — How long to wait, default 120.

Returns Status — The status.

local s = carried.wait("ada.avatar", 30); assert(s.state == "ready", s.detail)

modules/carried/heldBytes

heldBytes(): number

The bytes every carried mount holds in this engine's memory.

print(carried.heldBytes())

modules/carried/list

list(): { Status }

The status of every carried mount of this session.

for _, m in carried.list() do print(m.key, m.state) end

modules/carried/manifest

manifest(key: string): string?

The manifest of the ready mount at key: the JSON bytes the content store served ($schema zero/closure/v1, root, and entries, one per file and folder with its world path, asset_guid, checksum, size_bytes, kind and origin, plus one engine entry per builtin it was built against). Their sha-256 is the mount's closureSha. Nil until the mount is ready.

Parameters

• key string — The mount's key.

local entries = require("@builtin::modules.json").decode(carried.manifest("ada.avatar")).entries

modules/carried/mount

mount(closureSha: string, options: MountOptions?): Status

Hold the carried mount of the closure whose manifest address is closureSha and start filling it, unless it is already held. The mount stands at /zero/runtime/carried/<key>/; a key holds one closure for as long as anyone uses it, and every mount of the same closure at the same key holds it once more. Answers at once with the mount's status (state resolving while it fills); carried.wait yields until it settles. Raises when the key is malformed, closureSha is no sha-256, or the key holds another closure.

Parameters

• closureSha string — The sha-256 hex digest of the closure's manifest.
• options MountOptions? (optional) — key: the mount's folder name (one path segment of letters, digits, ., _, -), default closure-<first 16 hex digits>; commit: the commit the closure was published at, stated in the status.

local m = carried.mount(sha, { key = "ada.avatar" }); local s = carried.wait(m.key)

modules/carried/mountDraft

mountDraft(assetPath: string, options: MountOptions?): Status

Hold a draft carried mount of the asset at assetPath, an asset of the open world's working tree (or of your home folder): the engine walks the asset and every asset its files reference, writes that closure and its manifest into the device's content cache, and mounts it from there the way a published closure mounts, labelled draft = true. It is this engine's alone. Mounting it again rebuilds it from the tree as it stands. A draft holding a home folder's content is that folder's: it is made for code that reaches the folder, and its files, listing, status and manifest answer that code alone. Raises, naming the folder, when the asset or anything it reaches is in a home folder the calling code does not reach.

Parameters

• assetPath string — The asset, e.g. /zero/source/chars/ada.avatar.
• options MountOptions? (optional) — key: the mount's folder name, default draft-<asset name>.

local d = carried.mountDraft("/zero/source/props/lamp.model"); carried.wait(d.key)

modules/carried/release

release(key: string): number

Let one holder of the mount at key go. The last one takes it down: its folder leaves /zero/runtime/carried/ and its bytes leave this engine's memory, while the device's content cache keeps them for the next mount. Raises when no mount is held at key.

Parameters

• key string — The mount's key.

carried.release("ada.avatar")

modules/carried/resolve

resolve(key: string, reference: string): string?

What reference, written by content of the closure at key, names: a guid the closure carries, a path of its world (props/lamp.model, /zero/source/props/lamp.model) or an identity of its world (props.lamp) answers the file inside the mount; a reference to the engine library answers the library asset, taken to the version of an engine builtin the closure was built against when the mount holds that version. The open world's own content answers none of it. Nil when nothing answers.

Parameters

• key string — The mount's key.
• reference string — A guid, path, identity or library reference.

local tex = carried.resolve("ada.avatar", "chars.ada_albedo")

modules/carried/status

status(key: string): Status?

Where the mount at key stands, as <key>/status states it: state is resolving, fetching, measuring, ready, refused or none; reason is a word saying why nothing is mounted (unreachable, notFound, incomplete) or why the closure was refused, with detail the sentence; bytesFetched / bytesTotal count the files read; measured counts files, folders and bytes per kind once ready; builtin names how each engine builtin the closure was built against resolves (host, mount, or hostOtherVersion with why). Nil when no mount is held at key, and when the mount holds a home folder's content the calling code does not reach.

Parameters

• key string — The mount's key.

print(carried.status("ada.avatar").state)

modules/carried/wait

wait(key: string, seconds: number?): Status

Yield until the mount at key settles (ready, refused or none) or seconds pass, and answer its status then. Raises when no mount is held at key, or when it holds a home folder's content the calling code does not reach.

Parameters

• key string — The mount's key.
• seconds number? (optional) — How long to wait, default 120.

local s = carried.wait("ada.avatar", 30); assert(s.state == "ready", s.detail)

typed/builtin//modules/api/engine/carried/carried/heldBytes

carried.heldBytes() -> number

The bytes every carried mount holds in this engine's memory.

Returns number — Bytes.

print(carried.heldBytes())

typed/builtin//modules/api/engine/carried/carried/list

carried.list() -> { Status }

The status of every carried mount of this session.

Returns { Status } — One status per mount.

for _, m in carried.list() do print(m.key, m.state) end

typed/builtin//modules/api/engine/carried/carried/manifest

carried.manifest(key: string) -> string?

The manifest of the ready mount at key: the JSON bytes the content store served ($schema zero/closure/v1, root, and entries, one per file and folder with its world path, asset_guid, checksum, size_bytes, kind and origin, plus one engine entry per builtin it was built against). Their sha-256 is the mount's closureSha. Nil until the mount is ready.

Parameters

• key string — The mount's key.

Returns string? — The manifest's bytes, or nil.

local entries = require("@builtin::modules.json").decode(carried.manifest("ada.avatar")).entries

typed/builtin//modules/api/engine/carried/carried/mount

carried.mount(closureSha: string, options: MountOptions?) -> Status

Hold the carried mount of the closure whose manifest address is closureSha and start filling it, unless it is already held. The mount stands at /zero/runtime/carried/<key>/; a key holds one closure for as long as anyone uses it, and every mount of the same closure at the same key holds it once more. Answers at once with the mount's status (state resolving while it fills); carried.wait yields until it settles. Raises when the key is malformed, closureSha is no sha-256, or the key holds another closure.

Parameters

• closureSha string — The sha-256 hex digest of the closure's manifest.
• options MountOptions (optional) — key: the mount's folder name (one path segment of letters, digits, ., _, -), default closure-<first 16 hex digits>; commit: the commit the closure was published at, stated in the status.

Returns Status — The mount's status.

local m = carried.mount(sha, { key = "ada.avatar" }); local s = carried.wait(m.key)

typed/builtin//modules/api/engine/carried/carried/mountDraft

carried.mountDraft(assetPath: string, options: MountOptions?) -> Status

Hold a draft carried mount of the asset at assetPath, an asset of the open world's working tree (or of your home folder): the engine walks the asset and every asset its files reference, writes that closure and its manifest into the device's content cache, and mounts it from there the way a published closure mounts, labelled draft = true. It is this engine's alone. Mounting it again rebuilds it from the tree as it stands. A draft holding a home folder's content is that folder's: it is made for code that reaches the folder, and its files, listing, status and manifest answer that code alone. Raises, naming the folder, when the asset or anything it reaches is in a home folder the calling code does not reach.

Parameters

• assetPath string — The asset, e.g. /zero/source/chars/ada.avatar.
• options MountOptions (optional) — key: the mount's folder name, default draft-<asset name>.

Returns Status — The mount's status.

local d = carried.mountDraft("/zero/source/props/lamp.model"); carried.wait(d.key)

typed/builtin//modules/api/engine/carried/carried/release

carried.release(key: string) -> number

Let one holder of the mount at key go. The last one takes it down: its folder leaves /zero/runtime/carried/ and its bytes leave this engine's memory, while the device's content cache keeps them for the next mount. Raises when no mount is held at key.

Parameters

• key string — The mount's key.

Returns number — How many holders still hold it.

carried.release("ada.avatar")

typed/builtin//modules/api/engine/carried/carried/resolve

carried.resolve(key: string, reference: string) -> string?

What reference, written by content of the closure at key, names: a guid the closure carries, a path of its world (props/lamp.model, /zero/source/props/lamp.model) or an identity of its world (props.lamp) answers the file inside the mount; a reference to the engine library answers the library asset, taken to the version of an engine builtin the closure was built against when the mount holds that version. The open world's own content answers none of it. Nil when nothing answers.

Parameters

• key string — The mount's key.
• reference string — A guid, path, identity or library reference.

Returns string? — A VFS path, or nil.

local tex = carried.resolve("ada.avatar", "chars.ada_albedo")

typed/builtin//modules/api/engine/carried/carried/status

carried.status(key: string) -> Status?

Where the mount at key stands, as <key>/status states it: state is resolving, fetching, measuring, ready, refused or none; reason is a word saying why nothing is mounted (unreachable, notFound, incomplete) or why the closure was refused, with detail the sentence; bytesFetched / bytesTotal count the files read; measured counts files, folders and bytes per kind once ready; builtin names how each engine builtin the closure was built against resolves (host, mount, or hostOtherVersion with why). Nil when no mount is held at key, and when the mount holds a home folder's content the calling code does not reach.

Parameters

• key string — The mount's key.

Returns Status? — The status, or nil.

print(carried.status("ada.avatar").state)

typed/builtin//modules/api/engine/carried/carried/wait

carried.wait(key: string, seconds: number?) -> Status

Yield until the mount at key settles (ready, refused or none) or seconds pass, and answer its status then. Raises when no mount is held at key, or when it holds a home folder's content the calling code does not reach.

Parameters

• key string — The mount's key.
• seconds number (optional) — How long to wait, default 120.

Returns Status — The status.

local s = carried.wait("ada.avatar", 30); assert(s.state == "ready", s.detail)