> ## Documentation Index
> Fetch the complete documentation index at: https://b01t.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PackageRegistry: Publish and Resolve Algorithms

> Reference for PackageRegistry and PackageMeta: publish, discover, serialize, and resolve dependencies for b01t algorithm packages.

`PackageRegistry` is an in-memory catalog for b01t algorithm packages. You publish a compiled program as a `PackageMeta` entry, then retrieve it by name or tag, resolve its dependencies in topological order, and save or load the entire registry to a JSON file. A global `DEFAULT_REGISTRY` instance is available for convenience.

```python theme={null}
from b01t import PackageMeta, PackageRegistry, DEFAULT_REGISTRY
```

***

## PackageMeta

`PackageMeta` is a dataclass that describes a published algorithm package.

```python theme={null}
from b01t import PackageMeta
from b01t import Effect

meta = PackageMeta(
    name="grover-oracle",
    effect="coherent",
    safe=True,
    tags=["search", "oracle"],
    docs="Grover phase oracle for 3-bit target.",
    inputs=[("ctrl", 3), ("tgt", 1)],
    version="1.0.0",
    depends_on=["hadamard-layer"],
)
```

<ResponseField name="name" type="str" required>
  Unique name for this package. Used as the registry key.
</ResponseField>

<ResponseField name="effect" type="str" required>
  Effect string: `"coherent"` or `"adaptive"`. Matches `Effect.value`.
</ResponseField>

<ResponseField name="safe" type="bool" required>
  Whether the program carries `Certification.SAFE` or `is_safe = True`.
</ResponseField>

<ResponseField name="tags" type="list[str]">
  Free-form tags for discovery. Default: `[]`.
</ResponseField>

<ResponseField name="docs" type="str">
  Human-readable description of the algorithm. Default: `""`.
</ResponseField>

<ResponseField name="inputs" type="list[tuple[str, int]]">
  Register specifications as `(name, size)` tuples, in order. Default: `[]`.
</ResponseField>

<ResponseField name="version" type="str">
  Semantic version string. Default: `"0.1.0"`.
</ResponseField>

<ResponseField name="depends_on" type="list[str]">
  Names of other packages this package depends on. Used for topological resolution. Default: `[]`.
</ResponseField>

<ResponseField name="ir" type="IRProgram | None">
  Attached broad IR program, if any. Not persisted in JSON (`save` stores its text dump; `load` does not restore it). Default: `None`.
</ResponseField>

<ResponseField name="exact_program" type="ExactProgram | None">
  Attached exact program. Persisted to JSON using `exact-oracle-v1` format when `save` is called. Restored on `load`. Default: `None`.
</ResponseField>

***

## PackageRegistry

### publish

```python theme={null}
registry.publish(meta: PackageMeta) -> None
```

Adds or replaces the package entry for `meta.name`.

<ParamField path="meta" type="PackageMeta" required>
  The package metadata to store. If a package with the same name already exists, it is overwritten.
</ParamField>

***

### get

```python theme={null}
registry.get(name: str) -> Optional[PackageMeta]
```

Retrieves the package with the given name, or `None` if not found.

<ParamField path="name" type="str" required>
  The exact package name to look up.
</ParamField>

***

### find\_by\_tag

```python theme={null}
registry.find_by_tag(tag: str) -> list[PackageMeta]
```

Returns all packages whose `tags` list includes `tag`.

<ParamField path="tag" type="str" required>
  The tag to search for.
</ParamField>

***

### all

```python theme={null}
registry.all() -> list[PackageMeta]
```

Returns all published packages as a list. Order is insertion order.

***

### save

```python theme={null}
registry.save(path: str | Path) -> None
```

Serializes the registry to a JSON file at `path`. Each entry includes all scalar fields. If a package has an `exact_program`, it is serialized using `exact-oracle-v1` format. Broad `IRProgram` objects are saved as their text dump but are not restored on load.

<ParamField path="path" type="str | Path" required>
  File path to write. The file is created or overwritten.
</ParamField>

***

### load

```python theme={null}
registry.load(path: str | Path) -> None
```

Deserializes packages from a JSON file previously written by `save` and merges them into this registry.

<ParamField path="path" type="str | Path" required>
  File path to read.
</ParamField>

***

### resolve

```python theme={null}
registry.resolve(name: str) -> list[PackageMeta]
```

Returns the transitive dependencies of `name` in topological order (dependencies first, then `name` itself). Raises `DSLValidationError` if a circular dependency is detected or a required package is missing.

<ParamField path="name" type="str" required>
  The package name to resolve.
</ParamField>

```python theme={null}
order = registry.resolve("my-algorithm")
for pkg in order:
    print(pkg.name)
# prints dependencies in load order, then "my-algorithm"
```

***

### dependency\_graph\_dot

```python theme={null}
registry.dependency_graph_dot() -> str
```

Returns a string in [DOT format](https://graphviz.org/doc/info/lang.html) describing the dependency graph of all published packages. You can pipe this to Graphviz to visualise the graph.

```python theme={null}
dot = registry.dependency_graph_dot()
print(dot)
# digraph packages {
#   rankdir=BT;
#   "grover" [label="grover\n[coherent]"];
#   "grover" -> "oracle";
#   ...
# }
```

***

## DEFAULT\_REGISTRY

`DEFAULT_REGISTRY` is a module-level `PackageRegistry` instance. Use it to publish packages without managing your own registry object.

```python theme={null}
from b01t import DEFAULT_REGISTRY, PackageMeta

DEFAULT_REGISTRY.publish(PackageMeta(
    name="my-oracle",
    effect="coherent",
    safe=True,
))

pkg = DEFAULT_REGISTRY.get("my-oracle")
```

***

## Full example

```python theme={null}
from b01t import (
    coherent, QReg, h, cx,
    PackageMeta, PackageRegistry,
    exact_program_to_dict,
)

@coherent
def bell(a: QReg, b: QReg) -> None:
    h(a[0])
    cx(a[0], b[0])

prog = bell.build_exact(("a", 1), ("b", 1))

registry = PackageRegistry()
registry.publish(PackageMeta(
    name="bell-pair",
    effect="coherent",
    safe=True,
    tags=["entanglement", "two-qubit"],
    docs="Prepares a Bell state from |00⟩.",
    inputs=[("a", 1), ("b", 1)],
    version="1.0.0",
    exact_program=prog,
))

# Save to disk
registry.save("registry.json")

# Load into a fresh registry
fresh = PackageRegistry()
fresh.load("registry.json")

loaded = fresh.get("bell-pair")
print(loaded.exact_program.certification)  # Certification.SAFE
```