@stoneforge/core

Shared type definitions, branded IDs, error hierarchy, and utilities for the Stoneforge platform.

Overview

@stoneforge/core is the foundation layer for every Stoneforge package. It defines the canonical types for elements (tasks, entities, documents, plans, workflows, channels, messages), a structured error hierarchy with factory functions, a collision-resistant hierarchical ID system, and mention-parsing utilities.

Installation

npm install @stoneforge/core

Quick Start

import { generateId, generateChildId, parseId } from '@stoneforge/core/id';
import type { Task, Entity } from '@stoneforge/core/types';
import { notFound, invalidInput } from '@stoneforge/core/errors';

// Generate a root ID
const taskId = await generateId({ identifier: 'implement-auth', createdBy: 'el-abc' });

// Generate a child ID scoped to a parent
const subtaskId = generateChildId(taskId, 1);

// Parse an ID back into its components
const { hash, depth, isRoot } = parseId(subtaskId);

// Throw structured errors with factory functions
throw notFound('task', taskId);
throw invalidInput('title', 'Title is required');

API

Types

Core domain types used across all Stoneforge packages:

| Type | Description | |------|-------------| | Element | Base type for all stored objects | | Task | Work item with status, priority, assignments | | Entity | Actor in the system (human or agent) | | Document | Versioned content with content type | | Plan | Collection of related tasks with status tracking | | Workflow | Multi-step process with triggers | | Channel | Communication channel (direct, group) | | Message | Message within a channel | | Team | Named group of entities with roles | | Library | Collection of related documents | | Playbook | Templated multi-step process definition | | InboxItem | Notification items for entities | | Dependency | Blocking relationship between elements | | Event | Immutable record of a state change |

Errors

Structured error hierarchy with typed error codes:

import {
  StoneforgeError,
  ValidationError,
  NotFoundError,
  ConflictError,
  ConstraintError,
  StorageError,
  IdentityError,
} from '@stoneforge/core/errors';

// Factory functions for common errors
import {
  notFound,
  entityNotFound,
  invalidInput,
  alreadyExists,
} from '@stoneforge/core/errors';

ID System

Collision-resistant, hierarchical, human-readable IDs:

| Export | Description | |--------|-------------| | generateId(input) | Create a root ID from identifier + createdBy | | generateChildId(parentId, childNumber) | Create a scoped child ID | | generateIdHash(components) | Hash from ID components (identifier, createdBy, timestampNs, nonce) | | parseId(id) | Extract root, depth, components | | getIdRoot(id) | Get the root segment | | getIdParent(id) | Get the parent ID | | getIdDepth(id) | Get nesting depth | | isValidIdFormat(id) | Validate ID format | | isValidRootId(id) | Check if root-level ID | | isValidHierarchicalId(id) | Check if hierarchical ID |

Utilities

import { parseMentions, extractMentionedNames, hasMentions } from '@stoneforge/core/utils';

const mentions = parseMentions('Assign to @alice and @bob');
// [{ name: 'alice', ... }, { name: 'bob', ... }]

Entry Points

| Import | Contents | |--------|----------| | @stoneforge/core | Everything (re-exports all subpaths) | | @stoneforge/core/types | Type definitions only | | @stoneforge/core/errors | Error classes and factory functions | | @stoneforge/core/id | ID generation, parsing, validation | | @stoneforge/core/utils | Mention parsing utilities |

Part of Stoneforge — Apache-2.0