# Ludic packages

Ludic has a package manager built into the task runner (`bin/x`). It fetches,
resolves, stores and links third-party packages with no new infrastructure to
run — it drives plain `git` and rides on the Forgejo host and its release tags.

This is the v1 implementation of the direction decided in issue #63.

## The four decisions

| Axis | Ludic's choice |
| --- | --- |
| Where source comes from | **URL-as-identity, no registry.** The import path *is* the git location — `git.workshopsoft.io/user/pkg`. A `git tag vX.Y.Z` publishes a version. No account, no publish step, no index to run. |
| Version resolution | **Minimum Version Selection (MVS), Go-style.** A `require` is a *minimum*; the resolver picks, per module, the greatest of every required minimum, then keeps the reachable closure at those versions. Deterministic, no SAT solver. |
| Where dependencies live | **A content-addressed global store + per-project links (pnpm-style).** One immutable store keyed by a file-content hash (`~/.ludic/store/<sha256>`); each project gets a light linked view under `ludic_modules/` instead of a full copy. |
| Manifest / lock | **`package.ludic`** (declared deps + provided namespaces + kind + targets) and **`package.lock.ludic`** (resolved versions + content hashes). |

## Commands

```
x add <module>[@version]   add a dependency to package.ludic, then resolve + fetch + link
x get                      resolve every dependency in package.ludic, link them, write the lock
x update [module]          bump a dependency (or all) to its latest published version, then relock
x verify                   check every locked package against the store by content hash
x vendor                   copy the resolved packages into ./vendor for hermetic/offline builds
```

`x add` with no `@version` picks the latest published tag and records it as the
minimum. All the install commands print the resolved build list and write
`package.lock.ludic`.

## The manifest — `package.ludic`

A line-oriented manifest. `#` starts a comment; strings are double-quoted.

```
package "git.workshopsoft.io/orkun/greeter"   # this package's import path
version "1.2.0"                               # the version this checkout publishes
kind    source                                # source | prebuilt
provides "Greet"                              # the Foo.* namespace(s) it registers (repeatable)

require "git.workshopsoft.io/orkun/util" "1.0.0"   # a dependency and its minimum version

# a prebuilt lib also declares the targets it ships:
# kind    prebuilt
# targets "native-arm64" "wasm32"
```

A consumer project's manifest is the same file, usually with only `require`
lines (the `package`/`version` fields describe a *publishable* package and are
optional for a leaf application).

## The lockfile — `package.lock.ludic`

Generated by `x get`; do not edit by hand. One line per resolved module, pinning
its selected version, content hash, kind and provided namespaces:

```
# package.lock.ludic — generated by `x get`. Do not edit by hand.
lock 1
module "git.workshopsoft.io/orkun/greeter" version "1.2.0" hash "sha256:…" kind "source" provides "Greet"
module "git.workshopsoft.io/orkun/util"    version "1.0.0" hash "sha256:…" kind "source" provides "Util"
```

`x verify` rehashes each store entry and confirms the project links to it, so a
tampered or missing dependency is caught before it reaches a build.

## The store and the project view

Fetched packages live once in a global, immutable, content-addressed store:

```
~/.ludic/store/<sha256>/…        the package tree at a version (no .git)
~/.ludic/store/cache/<module>/   a git clone cache used during resolution
```

Each project gets a lightweight view — `ludic_modules/<import-path>` is a symlink
into the store — so many projects share one copy and nothing is duplicated
per-project. Override the store location with `$LUDIC_STORE`.

## Consuming a package — namespace registration

A **source package** ships plain Ludic. The consumer imports the package files by
their import path:

```
program App {
  import "git.workshopsoft.io/orkun/greeter/greet.ludic"
  entry { print(greet_hello()) }
}
```

The compiler resolves an import first relative to the importing file, then — for
a non-absolute path that is not found — under the package module root
(`$LUDIC_MODULES`, default `ludic_modules/`). So a fetched package's code is
spliced into the build and its namespace becomes available exactly the way the
built-in stdlib namespaces (Regex.\*, Grid.\*, …) are. Because Ludic compiles
ahead-of-time, a source package is compiled *into* the consumer's binary — no
ABI seam, and the whole-program guarantees (determinism, replay, `world_save`)
still hold.

Two packages may not register the same `Foo.*` namespace — a collision is a hard
error naming both modules.

## Prebuilt libraries

A `kind prebuilt` package ships a compiled artifact per target it declares in
`targets`. Resolution selects the artifact for the build target
(`$LUDIC_TARGET`, else `native-<arch>` for the host). If a needed target is not
shipped it is a hard error — unless the package also ships source, in which case
the source path is used. Prebuilt libs are the escape hatch for closed-source or
other-language code over the engine's stable C-ABI; source packages are the
default because they keep cross-compilation (including the wasm target) and the
compile-time ECS first-class.

## Offline / hermetic builds

`x vendor` copies the resolved packages out of the store into `./vendor`. Build
against the copy with `LUDIC_MODULES=vendor`, so the build needs neither the
network nor the global store.