Builtin Library
README.md
Source operations
Require @builtin::modules.sourceOperations to coordinate revision-checked changes to text files in a bound world.
capture(paths, directories?) waits for local writes in the named scope and captures authoritative file revisions and directory membership. It includes containing asset inventories for their derived checksums. The returned snapshot is frozen and names its world and branch.
revisionToken(snapshot) returns a deterministic token for the guarded world, branch, file revisions and directory membership. A later capture with the same guarded revisions has the same token; guarded changes invalidate it. It leaves the snapshot and source files unchanged.
source(snapshot, path) reads a SourceEditing snapshot whose identity and storage checksum match the captured row. Use SourceEditing's call discovery and exact-range helpers to select the intended declaration and scope.
local Ops = require("@builtin::modules.sourceOperations")
local Source = require("@builtin::modules.sourceEditing")
local path = "/zero/source/scenes/main.scene/build.luau"
local snapshot = Ops.capture({path})
local source = Ops.source(snapshot, path)
local calls = Source.calls(source, "asset.resolve")
assert(calls[1], "select an asset.resolve declaration in this builder")
local edit = Source.replace(calls[1].arguments[1], Source.literal("props.Table"))
local plan = Ops.plan(snapshot, {{path=path, source=Source.preview(source, {edit})}})
-- Review plan.uploads and the selected declaration's affected outputs.
local prepared = Ops.prepare(plan)
assert(prepared.state == "prepared", prepared.reason)
local result = Ops.commit(plan.operation, plan.scope)
assert(result.state == "committed", result.reason)
plan(snapshot, changes) accepts disjoint text-file replacements and explicit {path=..., remove=true} removals. It preserves existing file identities, allocates identities for new files, derives candidate reference tables and recomputes containing asset checksums through the engine. Every mutation must be covered by the captured read set. Create asset containers through asset.create, then plan changes to their source files. Directory inventories participate in revision checks, including additions at previously absent paths. References are derived against the current asset registry and the captured prior reference table.
plan enforces ordinary source-write permissions, including computed-output protection declared by an asset type. A compiler uses materialize(snapshot, changes) to include its computed outputs together with their inputs. Materialization keeps the same revision, directory, identity and reference checks and respects world and library write permissions.
prepare(plan) first retains the exact request and its candidate pins, then uploads missing candidates under those pins. It returns prepared state once every candidate is available, already committed state after a completed operation, or failed state with the operation id retained. Repeated preparation uploads only missing candidates. Interrupted preparation is inspectable as awaitingCandidates, with the missing content hashes; resume with the retained plan or cancel it. commit(id, scope?) applies the retained request against its read set. A committed result acknowledges server persistence; scene activation observes the resulting files.
inspect(id, scope?) returns committed, prepared, awaitingCandidates, cancelled or missing state. Prepared records include the exact request, and committed records include the receipt. Use the same operation identity after a lost reply. pending() enumerates this identity's unfinished operations in the bound world and branch. cancel(id, scope?) releases a prepared operation's candidates and makes its identity terminal. Failed commits retain their prepared record for inspection and explicit resolution.