src/lock/world.bend checks

raw source on the hub · import 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/world.bend as World

lock/world: everything ez lock reads, as one value, and what the lock may depend on in it. The planner (lock/plan.bend) is a pure function of a World; the interpreter (lock/run.bend) gathers one, answering each question the planner asks by IO, and executes the plan the planner returns. The design is docs/rfc/ez-lock-planner.md.

A World is the ledger's text, the committed .bend files, one answer per package the planner asked about, and, under --upgrade, one answer per question the upgrade asked (lock/up.bend). There is no field for the environment, the clock, untracked files, .ez/origins.toml or BEND_LIB's path, because the lock reads none of them. A package a dependency imports by <name>@<version> adds two questions, asked only when the ledger does not name it: the lock being rewritten, which already records every name it resolved, and, for a name it does not record, what the hub says the name names. Both are answers like any other, and enter the lock through their verdicts.

9 imports

import Base
import ./lock.bend as L
import ./up.bend as Up
import ../ledger/upgrade.bend as U
import ../ledger/manifest.bend as M
import ../pkg/pkg.bend as K
import ../hub/hub.bend as Web
import ../share/sha.bend as Sha
import ../share/say.bend as Say

Types

type Args source · line 32 · raw

Data

the command as it was run: --upgrade, the name --package gave ("" for none), and the directory it runs in, which is the project root. A relative path source is recorded as it was given, relative to that root, and every question the lock asks about it names it anchored there, as the planner computes it (P.anchor.src, Up.anchor).

Args

@upgrade:Bool -> @only:String -> @here:String -> Args

type Source source · line 36 · raw

Data

one committed .bend file: its path and its text

Source
```
@at:String -> @text:String -> Source
```

type Listing source · line 41 · raw

Data

what git ls-files '*.bend' answered: the committed sources, or why git could not list them

Listed
```
@files:List<&2, Source> -> Listing
```
Unlisted
```
@why:String -> Listing
```

type How source · line 49 · raw

Data

how the interpreter came by a package's bytes. A tree already under BEND_LIB, vendored or left by an earlier lock, was read from there. One that was not was cloned at the rev the ledger pins, and weighed. A hub package was served by the hub.

Lib
```
How
```
Clone
```
@nar:String -> How
```
Served
```
How
```

type Ask source · line 59 · raw

Data

a question the planner asks, answered by one IO action: a package's manifest and the text of each file it names, where the source says to read it from, and the hub is where a hub package is served; the hash the hub says a <name>@<version> names, GET <hub>/name/<nv>; or the lock being rewritten, ez.lock.toml as it is.

Pkg

@hash:String -> @src:0x74799d3f846634a3d7461d4336d7c9d4/src/lock/lock.Src -> @hub:String -> Ask

Name
```
@nv:String -> @hub:String -> Ask
```
Lock
```
Ask
```

type Answer source · line 67 · raw

Data

the answer to one question: the manifest found and the text of each file it names, in the manifest's order; what the hub said a name names, as it said it; the lock's text, "" when there is none; or why IO could not answer

Got

@how:How -> @manifest:String -> @srcs:List<&2, String> -> Answer

Miss
```
@why:String -> Answer
```
Said
```
@text:String -> Answer
```
Locked
```
@text:String -> Answer
```

type Reply source · line 74 · raw

Data

one question, answered

Reply
```
@ask:Ask -> @answer:Answer -> Reply
```

type World source · line 80 · raw

Data

everything ez lock reads. The ledger is ez.toml's text, or None when there is no ez.toml. ups answers the upgrade's questions, and is empty for a plain lock, which asks none.

World

@args:Args -> @ledger:Maybe<&2, String> -> @listing:Listing -> @replies:List<&2, Reply> -> @ups:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/up.Reply> -> World

type Verdict source · line 87 · raw

Data

what the planner makes of one answer: the files and their texts, once every check passed, or why it refused them; or, for a name or the lock, the names it resolves, each to its hash

Ok

@files:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/pkg/pkg.Item> -> @srcs:List<&2, String> -> Verdict

No
```
@why:String -> Verdict
```

Named

@names:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/lock.Name> -> Verdict

type Judged source · line 93 · raw

Data

one package hash and its verdict

Judged

@hash:String -> @verdict:Verdict -> Judged

type Inputs source · line 102 · raw

Data

the part of a World the lock may depend on: the ledger the lock is made from, read, which under --upgrade is the one the upgrade leaves; why the upgrade refuses, "" when it does not; the committed sources; and the verdict on every package. A reply enters only through its verdict, so how the bytes arrived does not, and bytes that failed a check enter only as the refusal they caused.

Inputs

@ledger:0x74799d3f846634a3d7461d4336d7c9d4/src/ledger/manifest.Read -> @stop:String -> @listing:Listing -> @judged:List<&2, Judged> -> Inputs

Definitions

def args.upgrade source · line 106 · raw

@world:World -> Bool

whether the command was ez lock --upgrade

def args.only source · line 112 · raw

@world:World -> String

the name --package gave, "" for none

def here.of source · line 118 · raw

@args:Args -> String

the directory the command runs in

def args.here source · line 123 · raw

@world:World -> String

the directory the lock runs in, which is the project root

def ledger.of source · line 128 · raw

@world:World -> Maybe<&2, String>

the ledger's text

def lockfile source · line 133 · raw

String

the lock's path, which is fixed

def ask.hash source · line 139 · raw

@ask:Ask -> String

what a question asks about, which is the key its answer is judged and looked up under: a package's hash, a name, or the lock's path. A 0x name, a <name>@<version> and the lock's path are three different strings.

def sums.ok source · line 153 · raw

@fs:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/pkg/pkg.Item> -> @ss:List<&2, String> -> Bool

whether every text hashes to the sum its file is recorded with. A list of texts that is longer or shorter than the files is not the package.

def laid source · line 166 · raw

@fs:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/pkg/pkg.Item> -> @ss:List<&2, String> -> List<&2, Source>

each file with its text, as it is laid

def weigh source · line 178 · raw

@src:Source -> 0x74799d3f846634a3d7461d4336d7c9d4/src/pkg/pkg.Item

a laid file weighed by its own text

def weighs source · line 183 · raw

@ls:List<&2, Source> -> List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/pkg/pkg.Item>

every laid file weighed by its own text

def manifest source · line 192 · raw

@+ls:List<&2, Source> -> String

the manifest of the files laid, weighed by their own texts, which is the manifest a tree is laid with

def named source · line 196 · raw

@+ls:List<&2, Source> -> String

the 0x name of that manifest

def body.laid source · line 205 · raw

@ok:Bool -> @+hash:String -> @fs:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/pkg/pkg.Item> -> @ss:List<&2, String> -> Verdict

the verdict once the files, weighed by their own texts, were asked whether they hash to the name. Their manifest is the one the tree is laid with, and the manifest that was read hashes to the name already, so a package whose manifest is not written the way ez writes one (a line per file, in path order, each file once) is refused here rather than laid under a name its laid manifest does not hash to.

def body.sums source · line 214 · raw

@ok:Bool -> @+hash:String -> @+fs:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/pkg/pkg.Item> -> @+ss:List<&2, String> -> Verdict

the verdict once the texts were weighed against the manifest

def body.escape.go source · line 222 · raw

@clean:Bool -> @+bad:String -> @+hash:String -> @+fs:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/pkg/pkg.Item> -> @+ss:List<&2, String> -> Verdict

the verdict once each path was asked whether it escapes the package

def body.escape source · line 230 · raw

@+bad:String -> @+hash:String -> @+fs:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/pkg/pkg.Item> -> @+ss:List<&2, String> -> Verdict

the verdict once no path was found to escape the package

def body.named source · line 234 · raw

@ok:Bool -> @+hash:String -> @+manifest:String -> @+ss:List<&2, String> -> Verdict

the verdict once the manifest was known to be the one the hash names

def body source · line 248 · raw

@+hash:String -> @+manifest:String -> @+ss:List<&2, String> -> Verdict

a package's bytes, checked the same way whatever they came from: the manifest is the one the 0x name is the digest of, no path leaves the package, each text hashes to its file's sum, and the files, weighed by their own texts, hash to the name, which is ez fetch's check too. A tree under BEND_LIB is checked against its name like any other, so a stale or edited tree there is refused rather than locked.

def git.body source · line 253 · raw

@empty:Bool -> @+hash:String -> @+manifest:String -> @+ss:List<&2, String> -> Verdict

a git package that arrived with no files is refused, never locked as an empty table

def git.rule source · line 266 · raw

@named:Bool -> @+hash:String -> @+manifest:String -> @+ss:List<&2, String> -> Verdict

a git package's bytes under the rule its name was taken by. Since bend 2.0.27 a package holds the LICENSE files beside its sources, and the walk takes them along. A ledger written before names the same checkout without them, and that package is the checkout's too: when the walk's manifest does not hash to the name, the package without its LICENSE files is judged instead, and locked when that is the one the name is the digest of.

def git.weighed.go source · line 280 · raw

@same:Bool -> @+why:String -> @+hash:String -> @+manifest:String -> @+ss:List<&2, String> -> Verdict

a git package's bytes once its checkout was weighed. A tree read from BEND_LIB is judged as a clone that weighed to the narHash the ledger records, so the same bytes lock the same way whichever way they came.

def git.weighed source · line 287 · raw

@+why:String -> @+hash:String -> @+manifest:String -> @+ss:List<&2, String> -> Verdict

def git.how source · line 291 · raw

@how:How -> @+hash:String -> @+url:String -> @+rev:String -> @+nar:String -> @+manifest:String -> @+ss:List<&2, String> -> Verdict

a git package, by how it arrived

def hub.how source · line 309 · raw

@how:How -> @+hash:String -> @+manifest:String -> @+ss:List<&2, String> -> Verdict

a hub package, by how it arrived. Only the hub serves one.

def accept.src source · line 319 · raw

@src:0x74799d3f846634a3d7461d4336d7c9d4/src/lock/lock.Src -> @how:How -> @+hash:String -> @+manifest:String -> @+ss:List<&2, String> -> Verdict

a package's answer against where the ledger says it comes from

def hub.why source · line 329 · raw

@named:Bool -> @+hash:String -> @+hub:String -> @+why:String -> String

why a hub package could not be read. One the ledger names is explained the way a hub miss always was. One it does not name is said to be unnamed, since that, and not the hub, is what a person has to fix.

def miss.src source · line 338 · raw

@src:0x74799d3f846634a3d7461d4336d7c9d4/src/lock/lock.Src -> @named:Bool -> @+hash:String -> @+hub:String -> @+why:String -> String

why IO could not answer, said for where the package comes from

def said.ok source · line 347 · raw

@ok:Bool -> @+nv:String -> @+hash:String -> @+hub:String -> Verdict

what the hub said a name names, once it is known whether the answer is a 0x name

def said source · line 357 · raw

@+nv:String -> @+hub:String -> @+text:String -> Verdict

the hub's answer for a name: the 0x name it gives, trimmed as bend trims it, or a refusal when it gives none

def locked source · line 362 · raw

@text:String -> Verdict

the lock being rewritten: every name it records that bend would read back

def accept source · line 366 · raw

@+orgs:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/lock.Origin> -> @+hub:String -> @+hash:String -> @answer:Answer -> Verdict

one answer judged

def judge source · line 378 · raw

@+orgs:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/lock.Origin> -> @+hub:String -> @rs:List<&2, Reply> -> List<&2, Judged>

every reply judged, in the order they were given

def verdict.names source · line 388 · raw

@verdict:Verdict -> List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/lock.Name>

the names a verdict resolves: those of a name's or the lock's answer, and none for a package

def names.of source · line 400 · raw

@js:List<&2, Judged> -> List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/lock.Name>

every name the answers resolve, in the order they were given. The lock's answer is asked for before any name's, so a name it records is never put to the hub.

def parsed source · line 409 · raw

@ledger:Maybe<&2, String> -> 0x74799d3f846634a3d7461d4336d7c9d4/src/ledger/manifest.Read

the ledger, read. A missing one is refused as a ledger that does not parse: only ez init makes a ledger, and a lock of none is not a lock.

def origins source · line 417 · raw

@+ledger:Maybe<&2, String> -> List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/lock.Origin>

the origins a ledger records

def dep source · line 421 · raw

@world:World -> @name:String -> 0x74799d3f846634a3d7461d4336d7c9d4/src/ledger/manifest.Dep

the dependency ez.toml names name, as M.dep finds it

def ledger.hub source · line 426 · raw

@+ledger:Maybe<&2, String> -> String

the hub a ledger names

def next.up source · line 435 · raw

@up:Bool -> @+only:String -> @+ledger:Maybe<&2, String> -> @ups:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/up.Reply> -> 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/up.Next

a plain lock's is ez.toml as it is. An upgrade's is what the upgrade decides on its answers: the ledger it writes, or its refusal, or the questions it still has.

def next source · line 443 · raw

@args:Args -> @+ledger:Maybe<&2, String> -> @ups:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/up.Reply> -> 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/up.Next

what the upgrade decides on a World, or nothing around a plain lock

def next.origins source · line 448 · raw

@+nx:0x74799d3f846634a3d7461d4336d7c9d4/src/lock/up.Next -> List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/lock.Origin>

the origins the lock reads packages by

def next.hub source · line 452 · raw

@+nx:0x74799d3f846634a3d7461d4336d7c9d4/src/lock/up.Next -> String

the hub it names

def laid.reply source · line 457 · raw

@laid:0x74799d3f846634a3d7461d4336d7c9d4/src/lock/up.Laid -> @+orgs:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/lock.Origin> -> @+hub:String -> Reply

a tree the upgrade checked out at a new rev, as the answer to the package question the lock would ask about it: a clone, weighed

def laid.replies source · line 461 · raw

@ls:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/up.Laid> -> @+orgs:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/lock.Origin> -> @+hub:String -> List<&2, Reply>

def replies.of source · line 470 · raw

@+nx:0x74799d3f846634a3d7461d4336d7c9d4/src/lock/up.Next -> @replies:List<&2, Reply> -> List<&2, Reply>

the package answers the lock reads: the trees the upgrade checked out, then every answer the World holds

def judged.of source · line 475 · raw

@+nx:0x74799d3f846634a3d7461d4336d7c9d4/src/lock/up.Next -> @replies:List<&2, Reply> -> List<&2, Judged>

every package answer judged against the ledger the lock is made from

def sources.swap source · line 483 · raw

@+ss:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/ledger/upgrade.Swap> -> @fs:List<&2, Source> -> List<&2, Source>

every committed source with each hash the upgrade moved rewritten in its imports, as the upgrade writes it

def listing.swap source · line 490 · raw

@+ss:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/ledger/upgrade.Swap> -> @listing:Listing -> Listing

def listing.moved source · line 499 · raw

@ss:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/ledger/upgrade.Swap> -> @listing:Listing -> Listing

the committed sources as the lock reads them: as the upgrade leaves them, which is as they are when no hash moved, and always for a plain lock

def listing.of source · line 506 · raw

@+nx:0x74799d3f846634a3d7461d4336d7c9d4/src/lock/up.Next -> @listing:Listing -> Listing

def inputs.of source · line 510 · raw

@+nx:0x74799d3f846634a3d7461d4336d7c9d4/src/lock/up.Next -> @listing:Listing -> @replies:List<&2, Reply> -> Inputs

what a World is, as far as the lock may tell, once the upgrade decided

def inputs source · line 515 · raw

@world:World -> Inputs

what a World is, as far as the lock may tell

def reclone.how source · line 525 · raw

@how:How -> @+src:0x74799d3f846634a3d7461d4336d7c9d4/src/lock/lock.Src -> How

one answer as a fresh clone would have it: a tree read from BEND_LIB is instead cloned at the rev the ledger pins and weighed to the narHash the ledger records. Anything else is what it was.

def reclone.one source · line 534 · raw

@+orgs:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/lock.Origin> -> @+hash:String -> @answer:Answer -> Answer

def reclone.all source · line 547 · raw

@+orgs:List<&2, 0x74799d3f846634a3d7461d4336d7c9d4/src/lock/lock.Origin> -> @rs:List<&2, Reply> -> List<&2, Reply>

every answer as a fresh clone would have it. A tree the upgrade checked out is a clone already.

def reclone source · line 557 · raw

@world:World -> World

the World a fresh clone of the same commit gathers: the same ledger, the same committed sources, and every tree it would have read from BEND_LIB cloned and weighed instead, since a clone has nothing there