> For the complete documentation index, see [llms.txt](https://docs.holons.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.holons.io/software/library.md).

# Library

The **Library** domain in `@holons/core/library` is the shared lending catalog of a holon. It tracks the tools, books, equipment, and other items members make available to each other, who has borrowed what, when it is due back, and—through integration with [REA accounting](/software/rea-accounting.md)—the deposit and return events that recognize the practice of sharing.

Where a typical resource catalog is read-mostly, the Library is built around the verbs of borrowing and lending: items have state (`borrowed` / `available`), borrowers and timestamps, optional return-by dates, and an audit trail of ratings and issues.

## Item types

Standard categories are enumerated in `LIBRARY_TYPES`:

* `tool`
* `book`
* `equipment`
* `other`

Type detection (`detectItemType`) infers a sensible default from a description, so members can add items without picking a category explicitly. UIs use type to choose icons (`getItemIcon`) and display names (`getTypeDisplayName`).

## Item shape

```ts
interface LibraryItem {
  id: string;
  type: LibraryItemType;
  borrowed: boolean;
  createdBy?: number | string;        // owner (typically a user id)
  createdByUsername?: string;
  borrower: string | null;            // display name of current borrower
  borrowerId?: number | string | null;
  borrowerInitials?: string;
  borrowedAt?: Date | string;
  returnBy?: Date | string;
  returnedAt?: Date | string;
  category: string;
  description: string;
  value: number;                      // for deposit accounting
  created: Date | string;
  ratings?: Array<{ user?: string; rating: number; review?: string; date: Date | string }>;
  issues?: Array<{ reporter?: string; issue: string; date: Date | string; resolved: boolean }>;
}
```

The `value` field is what links Library to deposit accounting: when a member borrows an item, a deposit event is emitted with this amount; when they return it, the deposit is released.

## Operations

The public functions exported by `@holons/core/library`:

| Function                                         | Purpose                                                             |
| ------------------------------------------------ | ------------------------------------------------------------------- |
| `createLibraryItem(name, opts?)`                 | Build a new item (no persistence)                                   |
| `addItem(db, holonId, item)`                     | Persist a new item to HoloSphere                                    |
| `getItem(db, holonId, id)`                       | Read a single item                                                  |
| `listItems(db, holonId)`                         | Read all items in the holon's library                               |
| `filterItems(items, predicate)`                  | Pure: apply borrow-state / type / search filters                    |
| `setItemValue(db, holonId, id, value)`           | Update an item's deposit value                                      |
| `removeItem(db, holonId, id)`                    | Remove an item from the library                                     |
| `borrowItem(db, holonId, id, actor)`             | Mark item borrowed by an actor; returns a `BorrowItemResult`        |
| `returnItem(db, holonId, id)`                    | Mark item returned; returns a `ReturnItemResult`                    |
| `getLibraryStats(items)`                         | Pure: aggregate `LibraryStats` (total, borrowed, available, byType) |
| `computeBorrowerInitials(actor)`                 | Pure helper: 2-letter initials from a `BorrowActor`                 |
| `getItemDisplayTitle(item)`                      | Pure helper: human-friendly title                                   |
| `getItemIcon(item)` / `getTypeDisplayName(type)` | Pure presentation helpers                                           |

The split between **impure** persistence helpers (`addItem`, `borrowItem`, …) and **pure** presentation/aggregation helpers (`filterItems`, `getLibraryStats`, `computeBorrowerInitials`, …) means every UI uses the same code paths to render the same data—no per-UI re-implementations.

## Deposit accounting

When an item with a non-zero `value` is borrowed, the Library emits an REA event recording the deposit; when it is returned, a release event is emitted. These are produced via the [REA event factory](/software/rea-accounting.md):

```ts
recordBorrowAccounting(item, borrower, deps);
recordReturnAccounting(item, returner, deps);
```

`AccountingDeps` is a thin interface (`REAEventFactoryLike` + `REAEventStoreLike`) that lets the library module stay decoupled from REA—callers pass in the implementations they want, including no-op stubs for tests.

The resulting events feed the [scoring](/software/harvest-dashboard.md) system, so a holon that values the practice of lending can weight it in its value equation alongside other contribution types.

## Ratings and issues

Each item carries optional `ratings` (per-user rating + review) and `issues` (reporter, description, date, resolution status). These are stored on the item itself rather than as separate records, which keeps the data co-located with what it describes—simpler to query, simpler to display.

## MCP tool surface

The [MCP server](/software/mcp-server.md) exposes **11 tools** in the `library` domain — CRUD, borrowing, returning, search, tagging, stats. Agents connected via MCP can manage the catalog directly, including borrowing on behalf of their resolved actor.

## See also

* [REA accounting](/software/rea-accounting.md) — the event ledger that records deposits and returns
* [Harvest](/software/harvest-dashboard.md) — the monorepo this domain lives in
* [HolonsBot](/software/holonsbot.md) — the Telegram interface to library borrow/return flows


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.holons.io/software/library.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.