docs← Back to article

Markdown for LLMs

Packages, cases, and worlds

The source Markdown for this article. Copy it into your assistant or download it as a text file.

Download this articlePlain text ↗
# Packages, cases, and worlds

Three nouns carry the whole architecture:

- A **package** is a versioned folder of source files with a manifest
  (`law.toml`). The manifest says what the package is called, which
  version it is, and which other packages it needs.
- A **case package** is a package that holds one worked example: the
  facts of a case and the results expected from them.
- A **world** is the complete set of packages used to answer a
  question. It contains the root package and all of its direct and
  indirect dependencies. The lockfile fixes the version of every
  dependency, so the world is the same on every machine.

Packages, case packages, and worlds are **Available in the public
release** (S). Marks on this page follow the
[topic legend](/corpus/#how-this-topic-marks-confidence).

## The lab example: five packages, one world

The fictional parcel fixtures make the three nouns concrete. They are
cited by package id everywhere in this topic:

- `labparcels.iface` — the shared vocabulary: entities, one keyed
  relation, one enum. No rules, no sources, no dependencies.
- `labparcels.registry` — the fictional source act: pinned article text
  plus executable rules over the shared vocabulary.
- `labparcels.fees` and `labparcels.appeals` — two consumers of the
  registry, each adding its own rules without touching the source.
- `labparcels.case1` — the case package: one fact pattern with expected
  results over the world of the other four.

An arrow reads "depends on":

```text
labparcels.case1 ──┬──> labparcels.fees ─────┬──> labparcels.registry ──> labparcels.iface
                   ├──> labparcels.appeals ──┘
                   ├──> labparcels.registry
                   └──> labparcels.iface

fees and appeals also depend on labparcels.iface directly.
```

The world of `labparcels.case1` is all five packages. Its manifest
names each of the other four with one exact version (`fees` at 0.2.0,
the others at 0.1.0), and every answer the case gives is computed over
exactly those versions. The world of `labparcels.fees` alone is
smaller: `fees`, `registry`, and `iface`.

Interface, source, consumers, case: that layering is the pattern every
real subject area repeats. The [lab tour](/corpus/lab/) runs these
fixtures end to end.

## The package and its manifest

The manifest declares identity and needs: name, version, language,
namespace, dependencies, registries, and an optional canon-profile
slot. The slot is optional — the [manifest
schema](/protocols/schemas/package-manifest/#top-level-fields)
requires only the package block. When the slot names a profile, it
names exactly one, read at the lock root.

For the manifest fields in depth, see
[A package in the corpus](/tutorials/package/) and
[Package passports](/guide/package-passports/).

## The lockfile pins the dependencies

The manifest only requests versions; the lockfile records the exact
resolution. It holds:

- every package pinned to one version;
- content hashes for the compiled bytes;
- dependency edges;
- a resolution hash covering the profile block, expansions, and
  editions as presented.

Adding, installing, and updating packages write and check the
lockfile; the engine lock subcommand rechecks it on demand. **(S)**

The details — exact pins, directory registries, and offline transfer —
live on the [**Dependencies, locks, and registries**](/corpus/dependencies/) page of this topic.

## The world links the dependencies by name

Linking joins the root with its dependency nodes by package name. Three
rules apply:

- one version of a package per world;
- a single semantics line across the world;
- any content-identity collision between nodes is refused with a
  compiler diagnostic (LDC-E1107). **(S)**

Two operations share that link step, and they are not the same:

- **New-root linking** joins a fresh root with its locked dependencies.
  It happens inside asking, testing, and packing. For that reason there
  is deliberately no standalone build-the-world command. The absence is
  by design, not a missing feature: a world is always the locked world
  of some root, never a loose assembly.
- **Fixed-world-artifact execution** runs against already-linked world
  bytes carried in a release artifact. Serving, replaying a saved
  evaluation, and replaying a decision journal take the world as given
  and never link again.

For the idea worked by hand, see [Several packages and a
world](/tutorials/packages/).

## Commands that create and read a package

A new package starts from scaffolding:

```text
$ law --help
law — canon execution: packages, cases and questions (DECISION-0168)

  law init <dir> [--name <package>] [--template case|package] [--json]
```

The excerpt above is verbatim; the full listing covers the whole command
surface. The `case` template scaffolds a case package, the `package`
template a plain one. **(S)**

The full case-work recipe — context, snapshots, results, and tests — is
[N. Package, context, snapshots, case, result, and
test](/recipes/n-package/).

## Refusals and diagnostics

The low-level engine reads the same manifest back. Called with no target it
says what it needs — both lines below are verbatim error-stream output,
exit code 2 in each run:

```text
$ law engine manifest
manifest: requires law.toml or a package directory

$ law engine lock
lock: requires a package directory or law.toml
```

Manifest handling is command-line surface; the engine subcommands
themselves are internal tooling. **(S/I)**

Running a scenario command outside any project shows the project discovery
it relies on — verbatim error-stream output, exit code 2:

```text
$ law test
law test: REFUSAL: LPK-E0201: /private/tmp/empty-no-project: no law.toml here or above — pass the project via --project
  → run from the project or pass --project <dir>; a new one via `law init`
```

The fix is in the hint: run the command inside a project directory, pass
`--project <dir>`, or create a project with `law init`.

## Where to go next

- [**Dependencies, locks, and registries**](/corpus/dependencies/) — how the
  dependencies are resolved, pinned, and moved.
- [**Package boundaries: what the corpus answers**](/corpus/package-boundaries/) — the import surface and
  the limits of a corpus question.
- [Packages and cases](/cli/packages-cases/) — the command reference this
  page summarizes.