Library

Shared community library — tools, books, equipment borrowed and lent across a holon

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—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

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:

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 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 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.