@briefs/shared

Single source of truth for items, actors, and activities. Import Zod schemas for validation on clients, scripts, and assistant tools.

Imports

TypeScript

import {
  Item,
  itemSchema,
  itemCreateInputSchema,
  itemUpdateInputSchema,
  ItemStatus,
} from "@briefs/shared/item";

import { Activity, ActivityType } from "@briefs/shared/activity";
import { Actor } from "@briefs/shared/actor";

Item (schema v4)

Field	Type	Notes
schemaVersion	4	Schema version
id	UUID	Stable item identity
userId	string	Owning user identity
name	string	Display title
status	enum	open \| in_progress \| done \| cancelled
dueAt	ISO datetime?	Optional deadline
scheduledAt	ISO datetime?	Optional planned time
completedAt	ISO datetime?	Optional completion time
priority	enum?	low \| normal \| high \| urgent
description	string?	Optional write-up body
kind	string	Item type — task, note, ingest, etc.
ownerActorId	UUID	Actor who owns the item
context	string	Domain scope — defaults to core
originContext	string	Original domain scope — defaults to core
tags	string[]?	Optional labels
refs	ItemRef[]?	Typed links to other items
lifecycle	enum	active \| archived
source	ItemSource?	External provenance: system, externalId, optional externalUrl
ingestedAt	ISO datetime?	When Briefs first ingested the item
state	Record<string, unknown>?	Optional domain-specific state
occurredAt	ISO datetime	When it happened in the world
createdAt	ISO datetime	When the item was created
updatedAt	ISO datetime	When the item was last updated

Activity

Activities are append-only records keyed by itemId. They record who acted, what happened, when it happened, and when Briefs recorded it. Standard verbs include Create, Update, Move, Accept, Reject, Undo, Delete, and Merge.

Field	Type	Notes
schemaVersion	1	Schema version
id	UUID	Stable activity identity
type	string	Capitalized verb; namespaced verbs may use domain:Verb
actorId	UUID	Actor who performed the action
itemId	UUID	Item this activity applies to
origin	string?	Origin system or workflow
target	string?	Target of the action
summary	string?	Human-readable explanation; required for some verbs
occurredAt	ISO datetime	When the action happened in the world
recordedAt	ISO datetime	When Briefs recorded the action
result	ActivityResult?	Created item or field-level changes
clientKey	string?	Client-supplied idempotency key

Updates carry structured deltas in result.changes:

result.changes

{
  "result": {
    "changes": [
      { "field": "status", "before": "open", "after": "in_progress" }
    ]
  }
}

Actor

Actors identify the people and software that act on work. Person actors are ensured on first API use via GET /actors/me; Service and Application actors represent integrations and software clients. Every activity records an actorId.

Field	Type	Notes
schemaVersion	1	Schema version
id	UUID	Stable actor identity
type	enum	Person \| Service \| Application
name	string	Display name
identity	string	SSO principal, service principal, or application identity
createdAt	ISO datetime	When the actor was created

Source layout

shared/src/

actor/           who acted
activity/        append-only event log
item/            durable item + ingest source
common/          shared Zod helpers