ObneyAI/orc / .agents/skills/allium
allium
VerifiedGive your AI agents something more useful than a prompt. Velocity through clarity.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.4 KB |
| references/actioning-findings.md | markdown | 5.3 KB |
| references/assessing-specs.md | markdown | 5.5 KB |
| references/driving-the-loop.md | markdown | 7.8 KB |
| references/language-reference.md | markdown | 104.7 KB |
| references/migration-v1-to-v2.md | markdown | 13.5 KB |
| references/migration-v2-to-v3.md | markdown | 14.4 KB |
| references/patterns.md | markdown | 92.3 KB |
| references/recommended-loops.md | markdown | 13.9 KB |
| references/test-generation.md | markdown | 10.0 KB |
references/patterns.md
View on GitHub# Complete patterns
This library contains reusable patterns for common SaaS scenarios. Each pattern demonstrates specific Allium language features and can be adapted to your domain.
Patterns elide common cross-cutting entities (`Email`, `Notification`, `AuditLog`, etc.) for brevity. In a real specification, declare these as external entities or define them in a shared module.
| Pattern | Key Features Demonstrated |
|---------|---------------------------|
| Password Auth with Reset | Temporal triggers, token lifecycle, defaults, surfaces |
| Role-Based Access Control | Derived permissions, relationships, `requires` checks, surfaces |
| Invitation to Resource | Join entities, permission levels, tokenised actions, surfaces |
| Soft Delete & Restore | State machines, projections filtering deleted items |
| Notification Preferences | Sum types for notification variants, user preferences, digest batching, surfaces |
| Usage Limits & Quotas | Limit checks in `requires`, metered resources, plan tiers, surfaces |
| Comments with Mentions | Nested entities, parsing triggers, cross-entity notifications, surfaces |
| Integrating Library Specs | External spec references, configuration, config parameter references, responding to external triggers |
| Framework Integration Contract | Contract declarations, expression-bearing invariants, contract references, programmatic surfaces, external-API client (`demands`) |
---
## Pattern 1: Password Authentication with Reset
**Demonstrates:** Temporal triggers, token lifecycle, defaults, surfaces, multiple related rules
This pattern handles user registration, login and password reset: the foundation of most SaaS applications.
```
-- allium: 3
-- password-auth.allium
config {
min_password_length: Integer = 12
max_login_attempts: Integer = 5
lockout_duration: Duration = 15.minutes
reset_token_expiry: Duration = 1.hour
session_duration: Duration = 24.hours
}
------------------------------------------------------------
-- Entities
------------------------------------------------------------
entity User {
email: String
password_hash: String -- stored, never exposed
status: active | locked | deactivated
failed_login_attempts: Integer
locked_until: Timestamp?
-- Relationships
sessions: Session with user = this
reset_tokens: PasswordResetToken with user = this
-- Projections
active_sessions: sessions where status = active
pending_reset_tokens: reset_tokens where status = pending
-- Derived
is_locked: status = locked and locked_until > now
}
entity Session {
user: User
created_at: Timestamp
expires_at: Timestamp
status: active | expired | revoked
-- Derived
is_valid: status = active and expires_at > now
}
entity PasswordResetToken {
user: User
created_at: Timestamp
expires_at: Timestamp
status: pending | used | expired
-- Derived
is_valid: status = pending and expires_at > now
}
------------------------------------------------------------
-- Registration
------------------------------------------------------------
rule Register {
when: UserRegisters(email, password)
requires: not exists User{email: email}
requires: length(password) >= config.min_password_length
ensures: User.created(
email: email,
password_hash: hash(password), -- black box
status: active,
failed_login_attempts: 0
)
ensures: Email.created(
to: email,
template: welcome
)
}
------------------------------------------------------------
-- Login
------------------------------------------------------------
rule LoginSuccess {
when: UserLogsIn(email, password)
let user = User{email}
requires: exists user
requires: not user.is_locked
requires: verify(password, user.password_hash) -- black box
ensures: user.failed_login_attempts = 0
ensures: Session.created(
user: user,
created_at: now,
expires_at: now + config.session_duration,
status: active
)
}
rule LoginFailure {
when: UserLogsIn(email, password)
let user = User{email}
requires: exists user
requires: not user.is_locked
requires: not verify(password, user.password_hash)
ensures: user.failed_login_attempts = user.failed_login_attempts + 1
ensures:
if user.failed_login_attempts >= config.max_login_attempts:
user.status = locked
user.locked_until = now + config.lockout_duration
Email.created(to: user.email, template: account_locked)
}
rule LoginAttemptWhileLocked {
when: UserLogsIn(email, password)
let user = User{email}
requires: exists user
requires: user.is_locked
ensures: UserInformed(
user: user,
about: account_locked,
data: { unlocks_at: user.locked_until }
)
}
rule LockoutExpires {
when: user: User.locked_until <= now
requires: user.status = locked
ensures: user.status = active
ensures: user.failed_login_attempts = 0
ensures: user.locked_until = null
}
------------------------------------------------------------
-- Logout
------------------------------------------------------------
rule Logout {
when: UserLogsOut(session)
requires: session.status = active
ensures: session.status = revoked
}
rule SessionExpires {
when: session: Session.expires_at <= now
requires: session.status = active
ensures: session.status = expired
}
------------------------------------------------------------
-- Password Reset
------------------------------------------------------------
rule RequestPasswordReset {
when: UserRequestsPasswordReset(email)
let user = User{email}
requires: exists user
requires: user.status in {active, locked}
-- Invalidate any existing tokens
ensures:
for t in user.pending_reset_tokens:
t.status = expired
ensures:
let token = PasswordResetToken.created(
user: user,
created_at: now,
expires_at: now + config.reset_token_expiry,
status: pending
)
Email.created(
to: email,
template: password_reset,
data: { token: token }
)
}
rule CompletePasswordReset {
when: UserResetsPassword(token, new_password)
requires: token.is_valid
requires: length(new_password) >= config.min_password_length
let user = token.user
ensures: token.status = used
ensures: user.password_hash = hash(new_password)
ensures: user.status = active
ensures: user.failed_login_attempts = 0
ensures: user.locked_until = null
-- Invalidate all existing sessions
ensures:
for s in user.active_sessions:
s.status = revoked
ensures: Email.created(
to: user.email,
template: password_changed
)
}
rule ResetTokenExpires {
when: token: PasswordResetToken.expires_at <= now
requires: token.status = pending
ensures: token.status = expired
}
------------------------------------------------------------
-- Actors
------------------------------------------------------------
actor AuthenticatedUser {
identified_by: User where active_sessions.count > 0
}
------------------------------------------------------------
-- Surfaces
------------------------------------------------------------
surface Authentication {
facing visitor: User
provides:
UserLogsIn(email, password)
UserRegisters(email, password)
UserRequestsPasswordReset(email)
@guarantee NoSessionRequired
-- Accessible without an existing session.
@guidance
-- Show lockout status and unlock time when user.is_locked.
-- Validate password length client-side before submission.
}
surface PasswordReset {
facing visitor: User
context token: PasswordResetToken
exposes:
token.is_valid
token.expires_at
provides:
UserResetsPassword(token, new_password)
when token.is_valid
@guarantee NoSessionRequired
-- Accessible without an existing session.
}
surface AccountManagement {
facing user: AuthenticatedUser
exposes:
user.email
user.active_sessions
user.active_sessions.count
provides:
for session in user.active_sessions:
UserLogsOut(session)
UserRequestsPasswordReset(user.email)
}
```
**Key language features shown:**
- `config` block for configurable parameters (`config.min_password_length`, etc.)
- Derived values (`is_locked`, `is_valid`)
- Multiple rules for same trigger with different `requires` (login success vs failure)
- Temporal triggers with guards (`when: token: PasswordResetToken.expires_at <= now` with `requires: status = pending`)
- Projections for filtered collections (`pending_reset_tokens`)
- Bulk updates with `for` iteration
- Explicit `let` binding for created entities
- Black box functions (`hash()`, `verify()`)
- Surfaces with `facing` declaration and `for` iteration in `provides`
---
## Pattern 2: Role-Based Access Control (RBAC)
**Demonstrates:** Derived permissions, relationships, using permissions in `requires` clauses, surfaces
This pattern implements hierarchical roles where higher roles inherit permissions from lower ones.
```
-- allium: 3
-- rbac.allium
------------------------------------------------------------
-- Entities
------------------------------------------------------------
entity Role {
name: String -- e.g., "viewer", "editor", "admin"
permissions: Set<String> -- e.g., { "documents.read", "documents.write" }
inherits_from: Role? -- optional parent role
-- Derived: all permissions including inherited
effective_permissions:
permissions + (inherits_from?.effective_permissions ?? {})
}
entity User {
email: String
name: String
}
entity Workspace {
name: String
owner: User
-- Relationships
memberships: WorkspaceMembership with workspace = this
documents: Document with workspace = this
-- Projections
members: memberships -> user
admins: memberships where role.name = "admin" -> user
}
entity Document {
workspace: Workspace
created_by: User
title: String
content: String
}
entity DocumentView {
user: User
document: Document
at: Timestamp
}
-- Join entity connecting User, Workspace, and Role
entity WorkspaceMembership {
user: User
workspace: Workspace
role: Role
joined_at: Timestamp
-- Derived: check specific permissions
can_read: "documents.read" in role.effective_permissions
can_write: "documents.write" in role.effective_permissions
can_admin: "workspace.admin" in role.effective_permissions
}
------------------------------------------------------------
-- Defaults
------------------------------------------------------------
default Role viewer = {
name: "viewer",
permissions: { "documents.read" }
}
default Role editor = {
name: "editor",
permissions: { "documents.write" },
inherits_from: viewer
}
default Role admin = {
name: "admin",
permissions: { "workspace.admin", "members.manage" },
inherits_from: editor
}
------------------------------------------------------------
-- Rules
------------------------------------------------------------
rule CreateWorkspace {
when: UserCreatesWorkspace(user, name)
ensures:
let workspace = Workspace.created(
name: name,
owner: user
)
-- Owner automatically becomes admin
WorkspaceMembership.created(
user: user,
workspace: workspace,
role: admin,
joined_at: now
)
}
rule AddMember {
when: AddMemberToWorkspace(actor, workspace, new_user, role)
let actor_membership = WorkspaceMembership{user: actor, workspace: workspace}
requires: actor_membership.can_admin
requires: not exists WorkspaceMembership{user: new_user, workspace: workspace}
ensures: WorkspaceMembership.created(
user: new_user,
workspace: workspace,
role: role,
joined_at: now
)
ensures: Email.created(
to: new_user.email,
template: added_to_workspace,
data: { workspace: workspace, role: role }
)
}
rule ChangeMemberRole {
when: ChangeMemberRole(actor, workspace, target_user, new_role)
let actor_membership = WorkspaceMembership{user: actor, workspace: workspace}
let target_membership = WorkspaceMembership{user: target_user, workspace: workspace}
requires: actor_membership.can_admin
requires: exists target_membership
requires: target_user != workspace.owner -- can't change owner's role
ensures: target_membership.role = new_role
}
rule RemoveMember {
when: RemoveMemberFromWorkspace(actor, workspace, target_user)
let actor_membership = WorkspaceMembership{user: actor, workspace: workspace}
let target_membership = WorkspaceMembership{user: target_user, workspace: workspace}
requires: actor_membership.can_admin
requires: exists target_membership
requires: target_user != workspace.owner -- can't remove owner
ensures: not exists target_membership
}
rule LeaveWorkspace {
when: UserLeavesWorkspace(user, workspace)
let membership = WorkspaceMembership{user, workspace}
requires: exists membership
requires: user != workspace.owner -- owner can't leave
ensures: not exists membership
}
------------------------------------------------------------
-- Managing permissions on roles
------------------------------------------------------------
rule GrantPermission {
when: GrantPermission(actor, workspace, role, permission)
let actor_membership = WorkspaceMembership{user: actor, workspace: workspace}
requires: actor_membership.can_admin
requires: permission not in role.effective_permissions
ensures: role.permissions.add(permission)
}
rule RevokePermission {
when: RevokePermission(actor, workspace, role, permission)
let actor_membership = WorkspaceMembership{user: actor, workspace: workspace}
requires: actor_membership.can_admin
requires: permission in role.permissions -- only direct, not inherited
ensures: role.permissions.remove(permission)
}
------------------------------------------------------------
-- Using permissions in other rules
------------------------------------------------------------
rule CreateDocument {
when: CreateDocument(user, workspace, title, content)
let membership = WorkspaceMembership{user, workspace}
requires: membership.can_write
ensures: Document.created(
workspace: workspace,
created_by: user,
title: title,
content: content
)
}
rule ViewDocument {
when: ViewDocument(user, document)
let membership = WorkspaceMembership{user: user, workspace: document.workspace}
requires: membership.can_read
ensures: DocumentView.created(user: user, document: document, at: now)
}
------------------------------------------------------------
-- Actors
------------------------------------------------------------
actor WorkspaceAdmin {
within: Workspace
identified_by: User where WorkspaceMembership{user: this, workspace: within}.can_admin = true
}
actor WorkspaceEditor {
within: Workspace
identified_by: User where WorkspaceMembership{user: this, workspace: within}.can_write = true
}
actor WorkspaceViewer {
within: Workspace
identified_by: User where WorkspaceMembership{user: this, workspace: within}.can_read = true
}
------------------------------------------------------------
-- Surfaces
------------------------------------------------------------
surface WorkspaceMemberManagement {
facing admin: WorkspaceAdmin
context workspace: Workspace
exposes:
workspace.name
workspace.memberships
workspace.admins
provides:
AddMemberToWorkspace(admin, workspace, new_user, role)
ChangeMemberRole(admin, workspace, target_user, new_role)
when target_user != workspace.owner
RemoveMemberFromWorkspace(admin, workspace, target_user)
when target_user != workspace.owner
@guarantee OwnerProtection
-- The workspace owner's role cannot be changed or removed.
}
surface WorkspaceDocuments {
facing member: User
context workspace: Workspace
let membership = WorkspaceMembership{user: member, workspace: workspace}
exposes:
workspace.name
workspace.documents
provides:
CreateDocument(member, workspace, title, content)
when membership.can_write
for document in workspace.documents:
ViewDocument(member, document)
when membership.can_read
related:
WorkspaceMemberManagement(workspace)
when membership.can_admin
}
```
**Key language features shown:**
- Recursive derived values (`effective_permissions` includes inherited)
- Null-safe navigation (`inherits_from?.effective_permissions ?? {}`)
- Join entity lookup (`WorkspaceMembership{user: actor, workspace: workspace}`)
- Permission checks in `requires` clauses
- String set membership with `in` operator
- `.add()` and `.remove()` for set mutation in ensures clauses
- `not exists` as an outcome (removes the entity)
- Surfaces with role-based actors and permission-gated actions
- `related` clause for cross-surface navigation
---
## Pattern 3: Invitation to Resource
**Demonstrates:** Tokenised actions, permission levels, invitation lifecycle, guest vs member flows, surfaces
This pattern handles inviting users to collaborate on resources, whether they're existing users or not.
```
-- allium: 3
-- resource-invitation.allium
config {
invitation_expiry: Duration = 7.days
}
------------------------------------------------------------
-- Enumerations
------------------------------------------------------------
enum Permission { view | edit | admin }
------------------------------------------------------------
-- Entities
------------------------------------------------------------
entity Resource {
name: String
owner: User
-- Relationships
shares: ResourceShare with resource = this
invitations: ResourceInvitation with resource = this
-- Projections
active_shares: shares where status = active
pending_invitations: invitations where status = pending
}
entity ResourceShare {
resource: Resource
user: User
permission: Permission
status: active | revoked
created_at: Timestamp
-- Derived
can_view: permission in {view, edit, admin}
can_edit: permission in {edit, admin}
can_admin: permission = admin
can_invite: permission in {edit, admin} -- editors and admins can invite
}
entity ResourceInvitation {
resource: Resource
email: String
permission: Permission
invited_by: User
created_at: Timestamp
expires_at: Timestamp
status: pending | accepted | declined | expired | revoked
-- Derived
is_valid: status = pending and expires_at > now
}
------------------------------------------------------------
-- Inviting
------------------------------------------------------------
rule InviteToResource {
when: InviteToResource(inviter, resource, email, permission)
let inviter_share = ResourceShare{resource: resource, user: inviter}
let existing_invitation = ResourceInvitation{resource: resource, email: email}
requires: inviter = resource.owner or inviter_share.can_invite
requires: permission in {view, edit} -- can't invite as admin unless owner
or (permission = admin and inviter = resource.owner)
requires: not exists ResourceShare{resource: resource, user: User{email: email}}
requires: not exists existing_invitation or not existing_invitation.is_valid
ensures: ResourceInvitation.created(
resource: resource,
email: email,
permission: permission,
invited_by: inviter,
created_at: now,
expires_at: now + config.invitation_expiry,
status: pending
)
ensures: Email.created(
to: email,
template: resource_invitation,
data: {
resource: resource,
inviter: inviter,
permission: permission
}
)
}
------------------------------------------------------------
-- Accepting (existing user)
------------------------------------------------------------
rule AcceptInvitationExistingUser {
when: ExistingUserAcceptsInvitation(invitation, user)
requires: invitation.is_valid
requires: user.email = invitation.email
ensures: invitation.status = accepted
ensures: ResourceShare.created(
resource: invitation.resource,
user: user,
permission: invitation.permission,
status: active,
created_at: now
)
ensures: Notification.created(
to: invitation.invited_by,
template: invitation_accepted,
data: { resource: invitation.resource, user: user }
)
}
------------------------------------------------------------
-- Accepting (new user - triggers signup flow)
------------------------------------------------------------
rule AcceptInvitationNewUser {
when: NewUserAcceptsInvitation(invitation, email, name, password)
requires: invitation.is_valid
requires: email = invitation.email
requires: not exists User{email: email}
ensures:
let user = User.created(
email: email,
name: name,
password_hash: hash(password),
status: active
)
invitation.status = accepted
ResourceShare.created(
resource: invitation.resource,
user: user,
permission: invitation.permission,
status: active,
created_at: now
)
Notification.created(
to: invitation.invited_by,
template: invitation_accepted,
data: { resource: invitation.resource, user: user }
)
}
------------------------------------------------------------
-- Declining and expiring
------------------------------------------------------------
rule DeclineInvitation {
when: DeclineInvitation(invitation)
requires: invitation.is_valid
ensures: invitation.status = declined
}
rule InvitationExpires {
when: invitation: ResourceInvitation.expires_at <= now
requires: invitation.status = pending
ensures: invitation.status = expired
}
rule RevokeInvitation {
when: RevokeInvitation(actor, invitation)
let actor_share = ResourceShare{resource: invitation.resource, user: actor}
requires: invitation.status = pending
requires: actor = invitation.resource.owner or actor_share.can_admin
ensures: invitation.status = revoked
}
------------------------------------------------------------
-- Managing shares
------------------------------------------------------------
rule ChangeSharePermission {
when: ChangeSharePermission(actor, share, new_permission)
let actor_share = ResourceShare{resource: share.resource, user: actor}
requires: actor = share.resource.owner or actor_share.can_admin
requires: share.user != share.resource.owner -- can't change owner
requires: share.status = active
ensures: share.permission = new_permission
}
rule RevokeShare {
when: RevokeShare(actor, share)
let actor_share = ResourceShare{resource: share.resource, user: actor}
requires: actor = share.resource.owner or actor_share.can_admin
requires: share.user != share.resource.owner
requires: share.status = active
ensures: share.status = revoked
ensures: Notification.created(
to: share.user,
template: access_revoked,
data: { resource: share.resource }
)
}
------------------------------------------------------------
-- Surfaces
------------------------------------------------------------
surface ResourceSharing {
facing sharer: User
context resource: Resource
let share = ResourceShare{resource: resource, user: sharer}
exposes:
resource.active_shares
resource.pending_invitations
provides:
InviteToResource(sharer, resource, email, permission)
when sharer = resource.owner or share.can_invite
for invitation in resource.pending_invitations:
RevokeInvitation(sharer, invitation)
when sharer = resource.owner or share.can_admin
for s in resource.active_shares:
ChangeSharePermission(sharer, s, new_permission)
when sharer = resource.owner or share.can_admin
RevokeShare(sharer, s)
when sharer = resource.owner or share.can_admin
@guarantee OwnerCannotBeRevoked
-- The resource owner's access cannot be revoked or downgraded.
}
surface InvitationResponse {
facing recipient: User
context invitation: ResourceInvitation where email = recipient.email
exposes:
invitation.resource.name
invitation.permission
invitation.invited_by.name
invitation.expires_at
invitation.is_valid
provides:
ExistingUserAcceptsInvitation(invitation, recipient)
when invitation.is_valid
DeclineInvitation(invitation)
when invitation.is_valid
}
```
**Key language features shown:**
- Named enum (`Permission`) shared across `ResourceShare` and `ResourceInvitation`
- Complex permission logic in `requires`
- Distinct trigger names for different parameter shapes (`ExistingUserAcceptsInvitation` vs `NewUserAcceptsInvitation`)
- Invitation lifecycle (pending → accepted/declined/expired/revoked)
- Checking existence with `exists` keyword
- Permission escalation prevention (`can't invite as admin unless owner`)
- Surfaces for both resource owner and invitation recipient boundaries
- Conditional `provides` with `for` iteration over collections
---
## Pattern 4: Soft Delete & Restore
**Demonstrates:** Simple state machines, projections that filter deleted items, retention policies
This pattern implements soft delete where items appear deleted but can be restored within a retention period.
```
-- allium: 3
-- soft-delete.allium
config {
retention_period: Duration = 30.days
}
------------------------------------------------------------
-- Entities
------------------------------------------------------------
entity Document {
workspace: Workspace
title: String
content: String
created_by: User
created_at: Timestamp
status: active | deleted
deleted_at: Timestamp?
deleted_by: User?
-- Derived
is_active: status = active
retention_expires_at: deleted_at + config.retention_period
can_restore: status = deleted and retention_expires_at > now
}
-- Extend Workspace to show how projections filter
entity Workspace {
name: String
-- Relationships
all_documents: Document with workspace = this
-- Projections (what users typically see)
documents: all_documents where status = active
deleted_documents: all_documents where status = deleted
restorable_documents: all_documents where can_restore = true
}
------------------------------------------------------------
-- Rules
------------------------------------------------------------
rule DeleteDocument {
when: DeleteDocument(actor, document)
let membership = WorkspaceMembership{user: actor, workspace: document.workspace}
requires: document.status = active
requires: actor = document.created_by or membership.can_admin
ensures: document.status = deleted
ensures: document.deleted_at = now
ensures: document.deleted_by = actor
}
rule RestoreDocument {
when: RestoreDocument(actor, document)
let membership = WorkspaceMembership{user: actor, workspace: document.workspace}
requires: document.can_restore
requires: actor = document.deleted_by or membership.can_admin
ensures: document.status = active
ensures: document.deleted_at = null
ensures: document.deleted_by = null
}
rule PermanentlyDelete {
when: PermanentlyDelete(actor, document)
let membership = WorkspaceMembership{user: actor, workspace: document.workspace}
requires: document.status = deleted
requires: membership.can_admin
ensures: not exists document -- actually removed
}
rule RetentionExpires {
when: document: Document.retention_expires_at <= now
requires: document.status = deleted
ensures: not exists document
}
------------------------------------------------------------
-- Bulk operations
------------------------------------------------------------
rule EmptyTrash {
when: EmptyTrash(actor, workspace)
let membership = WorkspaceMembership{user: actor, workspace: workspace}
requires: membership.can_admin
ensures:
for d in workspace.deleted_documents:
not exists d
}
rule RestoreAll {
when: RestoreAllDeleted(actor, workspace)
let membership = WorkspaceMembership{user: actor, workspace: workspace}
requires: membership.can_admin
ensures:
for d in workspace.restorable_documents:
d.status = active
d.deleted_at = null
d.deleted_by = null
}
```
**Key language features shown:**
- `status` field with clear lifecycle
- Nullable timestamps (`deleted_at: Timestamp?`)
- Projections filtering by status (`documents: all_documents where status = active`)
- Derived values using config (`retention_expires_at: deleted_at + config.retention_period`)
- Temporal trigger for automatic cleanup (`when: document: Document.retention_expires_at <= now`)
- `not exists` for permanent removal, as distinct from soft delete
- Bulk operations with `for` iteration
---
## Pattern 5: Notification Preferences & Digests
**Demonstrates:** Sum types for notification variants, user preferences affecting rule behaviour, digest batching, temporal triggers, surfaces
This pattern handles in-app notifications with user-controlled email preferences and digest batching. It uses sum types to model different notification kinds, each carrying its own contextual data rather than pre-computed strings.
```
-- allium: 3
-- notifications.allium
-- Elided types: Comment, Resource, Task, Permission, DayOfWeek
-- (defined in other patterns or your domain spec)
config {
digest_window: Duration = 24.hours
}
------------------------------------------------------------
-- Enumerations
------------------------------------------------------------
enum EmailFrequency { immediately | daily_digest | never }
------------------------------------------------------------
-- Entities
------------------------------------------------------------
entity User {
email: String
name: String
next_digest_at: Timestamp?
-- Relationships
notification_setting: NotificationSetting with user = this
notifications: Notification with user = this
-- Projections
unread_notifications: notifications where status = unread
pending_email_notifications: notifications where email_status = pending
recent_pending_notifications: notifications where email_status = pending and created_at >= now - config.digest_window
}
entity NotificationSetting {
user: User
-- Per-type email preferences
email_on_mention: EmailFrequency
email_on_comment: EmailFrequency
email_on_share: EmailFrequency
email_on_assignment: EmailFrequency
-- Global settings
digest_enabled: Boolean
digest_day_of_week: Set<DayOfWeek> -- domain type; define as enum in your spec
}
------------------------------------------------------------
-- Notification Sum Type
------------------------------------------------------------
-- Base notification entity with shared fields
entity Notification {
user: User
created_at: Timestamp
status: unread | read | archived
email_status: pending | sent | skipped | digested
kind: MentionNotification | ReplyNotification | ShareNotification |
AssignmentNotification | SystemNotification
-- Derived
is_unread: status = unread
}
-- Someone @mentioned the user in a comment
variant MentionNotification : Notification {
comment: Comment
mentioned_by: User
}
-- Someone replied to the user's comment
variant ReplyNotification : Notification {
reply: Comment -- the new reply
original_comment: Comment -- the user's comment being replied to
replied_by: User
}
-- Someone shared a resource with the user
variant ShareNotification : Notification {
resource: Resource
shared_by: User
permission: Permission
}
-- Someone assigned a task to the user
variant AssignmentNotification : Notification {
task: Task
assigned_by: User
}
-- System-generated notification (catch-all for non-structured notifications)
variant SystemNotification : Notification {
title: String
body: String
link: String?
}
------------------------------------------------------------
-- Supporting Entities
------------------------------------------------------------
entity DigestBatch {
user: User
notifications: Set<Notification>
created_at: Timestamp
sent_at: Timestamp?
status: pending | sent | failed
}
------------------------------------------------------------
-- Creating notifications (type-specific rules)
------------------------------------------------------------
rule CreateMentionNotification {
when: UserMentioned(user, comment, mentioned_by)
let settings = user.notification_setting
requires: user != mentioned_by -- don't notify self
ensures: MentionNotification.created(
user: user,
comment: comment,
mentioned_by: mentioned_by,
created_at: now,
status: unread,
email_status: if settings.email_on_mention = never: skipped else: pending
)
}
rule CreateReplyNotification {
when: CommentReplied(original_author, reply, original_comment)
let settings = original_author.notification_setting
requires: original_author != reply.author -- don't notify self
ensures: ReplyNotification.created(
user: original_author,
reply: reply,
original_comment: original_comment,
replied_by: reply.author,
created_at: now,
status: unread,
email_status: if settings.email_on_comment = never: skipped else: pending
)
}
rule CreateShareNotification {
when: ResourceShared(user, resource, shared_by, permission)
let settings = user.notification_setting
requires: user != shared_by -- don't notify self
ensures: ShareNotification.created(
user: user,
resource: resource,
shared_by: shared_by,
permission: permission,
created_at: now,
status: unread,
email_status: if settings.email_on_share = never: skipped else: pending
)
}
rule CreateAssignmentNotification {
when: TaskAssigned(user, task, assigned_by)
let settings = user.notification_setting
requires: user != assigned_by -- don't notify self
ensures: AssignmentNotification.created(
user: user,
task: task,
assigned_by: assigned_by,
created_at: now,
status: unread,
email_status: if settings.email_on_assignment = never: skipped else: pending
)
}
rule CreateSystemNotification {
when: SystemNotificationTriggered(user, title, body, link)
ensures: SystemNotification.created(
user: user,
title: title,
body: body,
link: link,
created_at: now,
status: unread,
email_status: pending
)
}
------------------------------------------------------------
-- Immediate email sending
------------------------------------------------------------
rule SendImmediateEmail {
when: notification: Notification.created
let settings = notification.user.notification_setting
let preference =
if notification.kind = MentionNotification: settings.email_on_mention
else if notification.kind = ReplyNotification: settings.email_on_comment
else if notification.kind = ShareNotification: settings.email_on_share
else if notification.kind = AssignmentNotification: settings.email_on_assignment
else: immediately -- system notifications send immediately by default
requires: notification.email_status = pending
requires: preference = immediately
ensures: Email.created(
to: notification.user.email,
template: notification_immediate,
data: { notification: notification }
)
ensures: notification.email_status = sent
}
------------------------------------------------------------
-- Reading notifications
------------------------------------------------------------
rule MarkAsRead {
when: MarkNotificationRead(user, notification)
requires: notification.user = user
requires: notification.status = unread
ensures: notification.status = read
}
rule MarkAllAsRead {
when: MarkAllNotificationsRead(user)
ensures:
for n in user.unread_notifications:
n.status = read
}
rule ArchiveNotification {
when: ArchiveNotification(user, notification)
requires: notification.user = user
ensures: notification.status = archived
}
------------------------------------------------------------
-- Daily digest
------------------------------------------------------------
rule CreateDailyDigest {
when: user: User.next_digest_at <= now
requires: user.notification_setting.digest_enabled
let pending = user.recent_pending_notifications
requires: pending.count > 0
ensures: DigestBatch.created(
user: user,
notifications: pending,
created_at: now,
status: pending
)
ensures:
for n in pending:
n.email_status = digested
ensures: user.next_digest_at = next_digest_time(user) -- black box; uses digest_day_of_week
}
rule SendDigest {
when: batch: DigestBatch.created
requires: batch.status = pending
requires: batch.notifications.count > 0
ensures: Email.created(
to: batch.user.email,
template: daily_digest,
data: {
notifications: batch.notifications,
unread_count: batch.user.unread_notifications.count
}
)
ensures: batch.status = sent
ensures: batch.sent_at = now
}
------------------------------------------------------------
-- Preference updates
------------------------------------------------------------
rule UpdateNotificationPreferences {
when: UpdatePreferences(user, preferences)
let settings = user.notification_setting
ensures: settings.email_on_mention = preferences.mention
ensures: settings.email_on_comment = preferences.comment
ensures: settings.email_on_share = preferences.share
ensures: settings.email_on_assignment = preferences.assignment
ensures: settings.digest_enabled = preferences.digest_enabled
ensures: settings.digest_day_of_week = preferences.digest_days
}
------------------------------------------------------------
-- Surfaces
------------------------------------------------------------
surface NotificationCentre {
facing user: User
exposes:
user.unread_notifications
user.unread_notifications.count
user.notifications
provides:
for notification in user.unread_notifications:
MarkNotificationRead(user, notification)
MarkAllNotificationsRead(user)
when user.unread_notifications.count > 0
for notification in user.notifications:
ArchiveNotification(user, notification)
related:
NotificationPreferences(user)
}
surface NotificationPreferences {
facing user: User
context settings: NotificationSetting where user = user
exposes:
settings.email_on_mention
settings.email_on_comment
settings.email_on_share
settings.email_on_assignment
settings.digest_enabled
settings.digest_day_of_week
provides:
UpdatePreferences(user, preferences)
}
```
**Key language features shown:**
- **Sum types**: `kind: MentionNotification | ReplyNotification | ...` declares notification variants
- **Variant declarations**: Each notification kind uses `variant X : Notification` syntax
- **Variant-specific creation rules**: Each variant has its own creation rule with appropriate fields
- **Exhaustive kind checking**: `SendImmediateEmail` handles all variants explicitly
- Named enum (`EmailFrequency`) shared across preference fields
- User preferences stored as entity
- Temporal trigger for per-user digest scheduling (`when: user: User.next_digest_at <= now`)
- Digest batching with temporal trigger
- Surfaces with `related` clause linking notification centre to preferences
**Why sum types here?**
The previous approach used pre-computed `title`, `body`, and `link` strings:
```
Notification.created(
type: mention,
title: "{author} mentioned you",
body: truncate(comment.body, 100),
link: comment.parent.url
)
```
With sum types, each notification carries its actual entity references:
```
MentionNotification.created(
comment: comment,
mentioned_by: author
)
```
This is better because:
1. **Rich queries**: "Show all notifications about this document" queries the actual relationships
2. **Type safety**: Creating a `MentionNotification` requires a `comment` - you can't forget it
3. **Flexible rendering**: Display logic can access full entity data, not just truncated strings
4. **Consistency**: If a user's name changes, notification titles reflect the current name
---
## Pattern 6: Usage Limits & Quotas
**Demonstrates:** Limit checks in `requires`, metered resources, plan tiers, overage handling, surfaces
This pattern handles SaaS usage limits: different plans have different quotas, and usage is tracked and enforced.
```
-- allium: 3
-- usage-limits.allium
-- Elided types: Feature (define as enum in your spec)
------------------------------------------------------------
-- Entities
------------------------------------------------------------
entity Plan {
name: String -- e.g., "free", "pro", "enterprise"
-- Limits (null = unlimited)
max_documents: Integer?
max_storage_bytes: Integer?
max_team_members: Integer?
max_api_requests_per_day: Integer?
-- Features
features: Set<Feature> -- domain type; define in your spec
-- Derived
has_unlimited_documents: max_documents = null
has_unlimited_storage: max_storage_bytes = null
has_unlimited_members: max_team_members = null
}
entity Workspace {
name: String
owner: User
plan: Plan
api_key: String?
-- Relationships
documents: Document with workspace = this
memberships: WorkspaceMembership with workspace = this
usage: WorkspaceUsage with workspace = this
-- Derived checks
can_add_document: plan.has_unlimited_documents or documents.count < plan.max_documents
can_add_member: plan.has_unlimited_members or memberships.count < plan.max_team_members
can_use_feature(f): f in plan.features
}
entity WorkspaceUsage {
workspace: Workspace
storage_bytes_used: Integer
api_requests_today: Integer
next_reset_at: Timestamp
-- Derived (null when plan has no limit)
api_requests_remaining:
workspace.plan.max_api_requests_per_day - api_requests_today
has_api_quota: workspace.plan.max_api_requests_per_day != null
is_over_api_quota: has_api_quota and api_requests_remaining <= 0
}
entity UsageEvent {
workspace: Workspace
type: document_created | document_deleted | storage_added |
storage_removed | api_request | member_added | member_removed
amount: Integer
recorded_at: Timestamp
}
------------------------------------------------------------
-- Defaults
------------------------------------------------------------
default Plan free = {
name: "free",
max_documents: 10,
max_storage_bytes: 100_000_000, -- 100MB
max_team_members: 3,
max_api_requests_per_day: 100,
features: { basic_editing }
}
default Plan pro = {
name: "pro",
max_documents: 1000,
max_storage_bytes: 10_000_000_000, -- 10GB
max_team_members: 20,
max_api_requests_per_day: 10000,
features: { basic_editing, advanced_editing, api_access, integrations }
}
default Plan enterprise = {
name: "enterprise",
features: { basic_editing, advanced_editing, api_access, integrations,
sso, audit_log, custom_branding }
-- max_documents, max_storage_bytes, max_team_members,
-- max_api_requests_per_day all null (unlimited)
}
------------------------------------------------------------
-- Enforcing limits
------------------------------------------------------------
rule CreateDocument {
when: CreateDocument(user, workspace, title)
requires: workspace.can_add_document
ensures: Document.created(workspace: workspace, title: title, created_by: user)
ensures: UsageEvent.created(
workspace: workspace,
type: document_created,
amount: 1,
recorded_at: now
)
}
rule CreateDocumentLimitReached {
when: CreateDocument(user, workspace, title)
requires: not workspace.can_add_document
ensures: UserInformed(
user: user,
about: limit_reached,
data: {
limit_type: documents,
current: workspace.documents.count,
max: workspace.plan.max_documents,
upgrade_path: next_plan(workspace.plan)
}
)
}
rule AddTeamMember {
when: AddMember(actor, workspace, new_member, role)
requires: workspace.can_add_member
requires: WorkspaceMembership{user: actor, workspace: workspace}.can_admin
ensures: WorkspaceMembership.created(...)
ensures: UsageEvent.created(
workspace: workspace,
type: member_added,
amount: 1,
recorded_at: now
)
}
rule UseFeature {
when: UseFeature(user, workspace, feature)
requires: workspace.can_use_feature(feature)
ensures: FeatureUsed(workspace: workspace, feature: feature, by: user)
}
rule UseFeatureNotAvailable {
when: UseFeature(user, workspace, feature)
requires: not workspace.can_use_feature(feature)
ensures: UserInformed(
user: user,
about: feature_not_available,
data: {
feature: feature,
available_on: plans_with_feature(feature)
}
)
}
------------------------------------------------------------
-- API rate limiting
------------------------------------------------------------
rule RecordApiRequest {
when: ApiRequestReceived(workspace, endpoint)
let usage = workspace.usage
requires: not usage.is_over_api_quota
ensures: usage.api_requests_today = usage.api_requests_today + 1
ensures: UsageEvent.created(
workspace: workspace,
type: api_request,
amount: 1,
recorded_at: now
)
}
rule ApiRateLimitExceeded {
when: ApiRequestReceived(workspace, endpoint)
let usage = workspace.usage
requires: usage.is_over_api_quota
ensures: ApiRequestRejected(
workspace: workspace,
reason: rate_limit_exceeded,
data: { resets_at: usage.next_reset_at }
)
}
rule ResetDailyApiUsage {
when: usage: WorkspaceUsage.next_reset_at <= now
requires: usage.api_requests_today > 0 -- prevents re-firing when already reset
ensures: usage.api_requests_today = 0
ensures: usage.next_reset_at = usage.next_reset_at + 1.day
}
------------------------------------------------------------
-- Plan changes
------------------------------------------------------------
rule UpgradePlan {
when: UpgradePlan(workspace, new_plan)
let old_plan = workspace.plan
requires: new_plan.max_documents >= old_plan.max_documents
or new_plan.has_unlimited_documents
ensures: workspace.plan = new_plan
ensures: Email.created(
to: workspace.owner.email,
template: plan_upgraded,
data: { old_plan: old_plan, new_plan: new_plan }
)
}
rule DowngradePlan {
when: DowngradePlan(workspace, new_plan)
let old_plan = workspace.plan
-- Can only downgrade if under new plan's limits
requires: workspace.documents.count <= new_plan.max_documents
or new_plan.has_unlimited_documents
requires: workspace.memberships.count <= new_plan.max_team_members
or new_plan.has_unlimited_members
requires: workspace.usage.storage_bytes_used <= new_plan.max_storage_bytes
or new_plan.has_unlimited_storage
ensures: workspace.plan = new_plan
ensures: Email.created(
to: workspace.owner.email,
template: plan_downgraded,
data: { old_plan: old_plan, new_plan: new_plan }
)
}
rule DowngradeBlocked {
when: DowngradePlan(workspace, new_plan)
let over_documents =
workspace.documents.count > new_plan.max_documents
and not new_plan.has_unlimited_documents
let over_members =
workspace.memberships.count > new_plan.max_team_members
and not new_plan.has_unlimited_members
let over_storage =
workspace.usage.storage_bytes_used > new_plan.max_storage_bytes
and not new_plan.has_unlimited_storage
requires: over_documents or over_members or over_storage
ensures: UserInformed(
user: workspace.owner,
about: downgrade_blocked,
data: {
over_documents: over_documents,
over_members: over_members,
over_storage: over_storage
}
)
}
------------------------------------------------------------
-- Actors
------------------------------------------------------------
actor WorkspaceOwner {
within: Workspace
identified_by: User where this = within.owner
}
------------------------------------------------------------
-- Surfaces
------------------------------------------------------------
surface UsageDashboard {
facing owner: WorkspaceOwner
context workspace: Workspace
exposes:
workspace.plan
workspace.documents.count
workspace.plan.max_documents
workspace.memberships.count
workspace.plan.max_team_members
workspace.usage.storage_bytes_used
workspace.plan.max_storage_bytes
workspace.usage.api_requests_today
workspace.usage.api_requests_remaining
provides:
UpgradePlan(workspace, new_plan)
DowngradePlan(workspace, new_plan)
@guidance
-- Show progress bars for usage against limits.
-- Highlight when any resource is above 80% of its limit.
}
surface APIAccess {
facing consumer: Workspace
exposes:
consumer.usage.api_requests_remaining
consumer.plan.max_api_requests_per_day
provides:
ApiRequestReceived(consumer, endpoint)
when not consumer.usage.is_over_api_quota
@guarantee RateLimitEnforcement
-- Requests beyond the daily limit receive HTTP 429 with
-- reset time.
}
```
**Key language features shown:**
- Plan definitions with limits
- Derived boolean checks for limit enforcement (`can_add_document`, `can_add_member`)
- `requires` checking limits before actions
- Paired rules for success/failure cases
- Usage tracking with events
- Temporal trigger for daily reset (`when: usage: WorkspaceUsage.next_reset_at <= now`)
- Plan upgrade/downgrade logic with `let` binding to capture pre-mutation state
- Feature flags (`can_use_feature(f)`)
- Interaction surface for usage dashboard and API surface with rate limit guarantee
> **Exposing an API vs. calling one.** The `APIAccess` surface here models *exposing* a rate-limited API to consumers — the surface owner is the API, and the consumer is the `facing` party. To model the opposite case, where your spec is a *client* calling out to a third-party API, SDK, or MCP server, do not reach for `provides:`; use a module-level `contract` referenced with `demands` from the caller's side. See Pattern 9, *Example: Calling an external API (the `demands` side)*.
---
## Pattern 7: Comments with Mentions
**Demonstrates:** Nested entities, parsing for mentions, cross-entity notifications, threading, surfaces
This pattern implements comments with @mentions, including mention parsing and notification generation.
```
-- allium: 3
-- comments.allium
------------------------------------------------------------
-- Entities
------------------------------------------------------------
external entity User {
name: String
is_admin: Boolean
}
external entity Commentable {
-- Defined by the consuming spec (e.g., Document, Task, Project)
}
entity Comment {
parent: Commentable
reply_to: Comment? -- null for top-level, set for replies
author: User
body: String
created_at: Timestamp
edited_at: Timestamp?
status: active | deleted
-- Relationships
mentions: CommentMention with comment = this
replies: Comment with reply_to = this
reactions: CommentReaction with comment = this
-- Projections
active_replies: replies where status = active
-- Derived
is_reply: reply_to != null
is_edited: edited_at != null
mentioned_users: mentions -> user
thread_depth: if is_reply: reply_to.thread_depth + 1 else: 0
}
-- Join entity for mentions
entity CommentMention {
comment: Comment
user: User
notified: Boolean
}
entity CommentReaction {
comment: Comment
user: User
emoji: String -- e.g., "👍", "❤️", "🎉"
created_at: Timestamp
}
------------------------------------------------------------
-- Creating comments
------------------------------------------------------------
rule CreateComment {
when: CreateComment(author, parent, body)
let mentioned_usernames = parse_mentions(body) -- black box: extracts @username
let mentioned_users = users_with_usernames(mentioned_usernames) -- black box lookup
ensures:
let comment = Comment.created(
parent: parent,
reply_to: null,
author: author,
body: body,
created_at: now,
status: active
)
for user in mentioned_users:
CommentMention.created(
comment: comment,
user: user,
notified: false
)
}
rule CreateReply {
when: CreateReply(author, parent_comment, body)
let mentioned_usernames = parse_mentions(body)
let mentioned_users = users_with_usernames(mentioned_usernames) -- black box lookup
requires: parent_comment.status = active
requires: parent_comment.thread_depth < 3 -- limit nesting
ensures:
let comment = Comment.created(
parent: parent_comment.parent,
reply_to: parent_comment,
author: author,
body: body,
created_at: now,
status: active
)
for user in mentioned_users:
CommentMention.created(
comment: comment,
user: user,
notified: false
)
}
------------------------------------------------------------
-- Notifications for mentions and replies
------------------------------------------------------------
-- Trigger the notification system when someone is mentioned
rule NotifyMentionedUser {
when: mention: CommentMention.created
requires: mention.user != mention.comment.author -- don't notify self
requires: not mention.notified
ensures: mention.notified = true
ensures: UserMentioned(
user: mention.user,
comment: mention.comment,
mentioned_by: mention.comment.author
)
}
-- Trigger the notification system when someone's comment receives a reply
rule NotifyCommentAuthorOfReply {
when: comment: Comment.created
let original_author = comment.reply_to?.author
requires: comment.is_reply
requires: original_author != null
requires: original_author != comment.author -- don't notify self
requires: original_author not in comment.mentioned_users -- avoid double notify
ensures: CommentReplied(
original_author: original_author,
reply: comment,
original_comment: comment.reply_to
)
}
------------------------------------------------------------
-- Editing
------------------------------------------------------------
rule EditComment {
when: EditComment(actor, comment, new_body)
requires: actor = comment.author
requires: comment.status = active
let old_mentions = comment.mentioned_users
let new_mentioned_usernames = parse_mentions(new_body)
let new_mentioned_users = users_with_usernames(new_mentioned_usernames) -- black box lookup
let added_mentions = new_mentioned_users - old_mentions
let removed_mentions = old_mentions - new_mentioned_users
ensures: comment.body = new_body
ensures: comment.edited_at = now
-- Remove old mentions that are no longer present
ensures:
for user in removed_mentions:
not exists CommentMention{comment, user}
-- Add new mentions
ensures:
for user in added_mentions:
CommentMention.created(
comment: comment,
user: user,
notified: false
)
}
------------------------------------------------------------
-- Deleting
------------------------------------------------------------
rule DeleteComment {
when: DeleteComment(actor, comment)
requires: actor = comment.author or actor.is_admin
requires: comment.status = active
ensures: comment.status = deleted
-- Note: replies remain but show "deleted comment"
}
------------------------------------------------------------
-- Reactions
------------------------------------------------------------
rule AddReaction {
when: AddReaction(user, comment, emoji)
requires: comment.status = active
requires: not exists CommentReaction{comment, user, emoji}
ensures: CommentReaction.created(
comment: comment,
user: user,
emoji: emoji,
created_at: now
)
}
rule RemoveReaction {
when: RemoveReaction(user, comment, emoji)
let reaction = CommentReaction{comment, user, emoji}
requires: comment.status = active
requires: exists reaction
ensures: not exists reaction
}
rule ToggleReaction {
when: ToggleReaction(user, comment, emoji)
let existing = CommentReaction{comment, user, emoji}
requires: comment.status = active
ensures:
if exists existing:
not exists existing
else:
CommentReaction.created(
comment: comment,
user: user,
emoji: emoji,
created_at: now
)
}
------------------------------------------------------------
-- Surfaces
------------------------------------------------------------
surface CommentThread {
facing viewer: User
context parent: Commentable
let comments = Comments where parent = parent and status = active
exposes:
for comment in comments:
comment.author.name
comment.body
comment.created_at
comment.is_edited
comment.active_replies
comment.reactions
provides:
CreateComment(viewer, parent, body)
for comment in comments:
CreateReply(viewer, comment, body)
when comment.thread_depth < 3
EditComment(viewer, comment, new_body)
when viewer = comment.author
DeleteComment(viewer, comment)
when viewer = comment.author or viewer.is_admin
AddReaction(viewer, comment, emoji)
RemoveReaction(viewer, comment, emoji)
when exists CommentReaction{comment: comment, user: viewer, emoji: emoji}
@guidance
-- Show "edited" indicator when comment.is_edited.
-- Show "deleted comment" placeholder for deleted replies
-- rather than removing them from the thread.
}
```
**Key language features shown:**
- Nested/recursive entities (comments with replies)
- Entity creation triggers with binding (`when: mention: CommentMention.created`)
- Black box functions (`parse_mentions()`, `users_with_usernames()`)
- Explicit `let` binding for created entities
- Set operations (`new_mentioned_users - old_mentions`)
- Depth limiting (`thread_depth < 3`)
- **Cross-pattern triggers**: Emits `UserMentioned` and `CommentReplied` triggers that Pattern 5 handles
- Avoiding double notifications (`original_author not in comment.mentioned_users`)
- Toggle pattern with conditional ensures
- Join entity with three keys (`CommentReaction{comment, user, emoji}`)
- Surface with role-conditional actions (author can edit, author or admin can delete)
---
## Pattern 8: Integrating Library Specs
**Demonstrates:** External spec references with coordinates, configuration blocks, config parameter references, responding to external triggers, using external entities
Library specs are standalone specifications for common functionality: authentication providers, payment processors, email services. They define a contract that implementations must satisfy, and your application spec composes them in. Consuming specs can reference a library spec's config values as defaults for their own parameters, avoiding duplication when the values should track each other.
### Example: OAuth Authentication
This example shows integrating a library OAuth spec into your application. The OAuth spec handles the authentication flow; your application responds to authentication events and manages application-level user state.
```
-- allium: 3
-- app-auth.allium
------------------------------------------------------------
-- External Spec References
------------------------------------------------------------
-- Reference the OAuth spec from the library
-- The coordinate is immutable (git SHA), ensuring reproducible specs
use "github.com/allium-specs/oauth2/af8e2c1d" as oauth
-- Configure the OAuth spec for our application
oauth/config {
providers: { google, microsoft, github }
session_duration: 24.hours
refresh_window: 1.hour
link_expiry: 15.minutes
}
------------------------------------------------------------
-- Application Entities
------------------------------------------------------------
-- Our application's User entity, linked to OAuth identities
entity User {
email: String
name: String
avatar_url: String?
status: active | suspended | deactivated
created_at: Timestamp
last_login_at: Timestamp?
-- Relationship to OAuth sessions (from external spec)
sessions: oauth/Session with user = this
identities: oauth/Identity with user = this
-- Projections
active_sessions: sessions where status = active
-- Derived
is_authenticated: active_sessions.count > 0
linked_providers: identities -> provider
}
-- Application-specific user preferences
entity UserPreferences {
user: User
theme: light | dark | system
timezone: String
locale: String
}
------------------------------------------------------------
-- Responding to OAuth Events
------------------------------------------------------------
-- When a user authenticates for the first time, create our User entity
rule CreateUserOnFirstLogin {
when: oauth/AuthenticationSucceeded(identity, session)
requires: not exists User{email: identity.email}
ensures:
let user = User.created(
email: identity.email,
name: identity.display_name,
avatar_url: identity.avatar_url,
status: active,
created_at: now,
last_login_at: now
)
-- Link the OAuth identity to our user
identity.user = user
session.user = user
-- Create default preferences
UserPreferences.created(
user: user,
theme: system,
timezone: identity.timezone ?? "UTC",
locale: identity.locale ?? "en"
)
Email.created(
to: user.email,
template: welcome,
data: { user: user, provider: identity.provider }
)
}
-- When an existing user logs in, update last login
rule UpdateUserOnLogin {
when: oauth/AuthenticationSucceeded(identity, session)
let user = User{email: identity.email}
requires: exists user
requires: user.status = active
ensures: user.last_login_at = now
ensures: session.user = user
}
-- Block login for suspended users
rule BlockSuspendedUserLogin {
when: oauth/AuthenticationSucceeded(identity, session)
let user = User{email: identity.email}
requires: exists user
requires: user.status = suspended
ensures: session.status = revoked
ensures: UserInformed(
user: user,
about: account_suspended,
data: { contact: "support@example.com" }
)
}
-- When OAuth session expires, we might want to notify
rule NotifySessionExpiring {
when: session: oauth/Session.status transitions_to expiring
let user = session.user
requires: user != null
ensures: UserInformed(
user: user,
about: session_expiring,
data: { time_remaining: session.time_remaining }
)
}
-- Audit logging for security events
rule AuditLogout {
when: oauth/SessionTerminated(session, reason)
let user = session.user
requires: user != null
ensures: AuditLog.created(
user: user,
event: logout,
reason: reason,
timestamp: now,
metadata: { provider: session.provider, session_start: session.created_at }
)
}
------------------------------------------------------------
-- Application Actions Using OAuth
------------------------------------------------------------
rule LinkAdditionalProvider {
when: LinkProvider(user, provider)
requires: user.status = active
requires: provider not in user.linked_providers
-- Trigger the OAuth flow from the library spec
ensures: oauth/InitiateAuthentication(
provider: provider,
intent: link_account,
existing_user: user
)
}
rule UnlinkProvider {
when: UnlinkProvider(user, provider)
let identity = oauth/Identity{user, provider}
requires: user.status = active
requires: exists identity
requires: user.linked_providers.count > 1 -- must keep at least one
ensures: not exists identity
ensures: AuditLog.created(
user: user,
event: provider_unlinked,
timestamp: now,
metadata: { provider: provider }
)
}
```
### Example: Payment Processing
This example shows integrating a payment processor spec for subscription billing.
```
-- allium: 3
-- billing.allium
------------------------------------------------------------
-- External Spec References
------------------------------------------------------------
use "github.com/allium-specs/stripe-billing/b2c4e6f8" as stripe
stripe/config {
currency: USD
tax_calculation: automatic
proration: create_prorations
trial_period: 14.days
}
config {
trial_period: Duration = stripe/config.trial_period
extended_trial: Duration = stripe/config.trial_period * 2
trial_reminder_lead: Duration = 3.days
}
------------------------------------------------------------
-- Application Entities
------------------------------------------------------------
entity Organisation {
name: String
owner: User
billing_portal_url: String?
-- Link to Stripe customer (from external spec)
stripe_customer: stripe/Customer?
-- Relationships
subscription: Subscription with organisation = this
invoices: stripe/Invoice with stripe_customer = this
-- Derived
is_paying: subscription?.status = active
has_payment_method: stripe_customer?.default_payment_method != null
}
entity Subscription {
organisation: Organisation
plan: Plan
status: trialing | active | past_due | cancelled | expired
started_at: Timestamp
trial_ends_at: Timestamp?
current_period_ends_at: Timestamp
trial_reminder_sent: Boolean
-- Link to Stripe subscription
stripe_subscription: stripe/Subscription?
-- Derived
is_trial: status = trialing
days_until_renewal: current_period_ends_at - now
}
------------------------------------------------------------
-- Responding to Payment Events
------------------------------------------------------------
-- When Stripe confirms payment, activate or renew subscription
rule ActivateOnPaymentSuccess {
when: stripe/PaymentSucceeded(invoice)
let customer = invoice.customer
let org = Organisation{stripe_customer: customer}
let sub = org.subscription
requires: exists org
requires: sub.status in {trialing, past_due}
ensures: sub.status = active
ensures: sub.current_period_ends_at = invoice.period_end
ensures: Email.created(
to: org.owner.email,
template: payment_confirmed,
data: { amount: invoice.amount, next_billing: invoice.period_end }
)
}
-- Handle failed payments
rule HandlePaymentFailure {
when: stripe/PaymentFailed(invoice, failure_reason)
let customer = invoice.customer
let org = Organisation{stripe_customer: customer}
let sub = org.subscription
requires: exists org
ensures: sub.status = past_due
ensures: Email.created(
to: org.owner.email,
template: payment_failed,
data: {
reason: failure_reason,
retry_date: invoice.next_payment_attempt,
update_payment_url: org.billing_portal_url
}
)
ensures: UserInformed(
user: org.owner,
about: payment_failed,
data: { reason: failure_reason }
)
}
-- When trial is ending, remind user
rule TrialEndingReminder {
when: sub: Subscription.trial_ends_at - config.trial_reminder_lead <= now
requires: sub.status = trialing
requires: not sub.trial_reminder_sent
let org = sub.organisation
ensures: sub.trial_reminder_sent = true
ensures: Email.created(
to: org.owner.email,
template: trial_ending,
data: {
days_remaining: config.trial_reminder_lead,
plan: sub.plan,
has_payment_method: org.has_payment_method
}
)
}
-- Respond to subscription cancellation from Stripe
rule HandleSubscriptionCancelled {
when: stripe/SubscriptionCancelled(stripe_sub, reason)
let sub = Subscription{stripe_subscription: stripe_sub}
let org = sub.organisation
requires: exists sub
ensures: sub.status = cancelled
ensures: Email.created(
to: org.owner.email,
template: subscription_cancelled,
data: { reason: reason, access_until: sub.current_period_ends_at }
)
ensures: AuditLog.created(
user: org.owner,
event: subscription_cancelled,
timestamp: now,
metadata: { reason: reason, plan: sub.plan.name }
)
}
------------------------------------------------------------
-- Application Actions Using Stripe
------------------------------------------------------------
rule StartSubscription {
when: StartSubscription(org, plan)
requires: org.subscription = null or org.subscription.status in {cancelled, expired}
requires: org.stripe_customer != null
requires: org.has_payment_method
ensures: stripe/CreateSubscription(
customer: org.stripe_customer,
price: plan.stripe_price_id,
trial_period: if plan.has_trial: stripe/config.trial_period else: null
)
}
rule ChangePlan {
when: ChangePlan(org, new_plan)
let sub = org.subscription
requires: sub.status = active
requires: new_plan != sub.plan
ensures: stripe/UpdateSubscription(
subscription: sub.stripe_subscription,
new_price: new_plan.stripe_price_id
)
ensures: sub.plan = new_plan
}
rule CancelSubscription {
when: CancelSubscription(org, reason)
let sub = org.subscription
requires: sub.status in {active, trialing}
ensures: stripe/CancelSubscription(
subscription: sub.stripe_subscription,
at_period_end: true -- access continues until paid period ends
)
ensures: AuditLog.created(
user: org.owner,
event: cancellation_requested,
timestamp: now,
metadata: { reason: reason }
)
}
```
**Key language features shown:**
- External spec references with immutable coordinates (`use "github.com/.../abc123" as alias`)
- Configuration blocks for external specs (`oauth/config { ... }`)
- Config parameter references as defaults (`trial_period: Duration = stripe/config.trial_period`)
- Expression-form defaults derived from library config (`extended_trial: Duration = stripe/config.trial_period * 2`)
- Responding to external triggers (`when: oauth/AuthenticationSucceeded(...)`)
- Trigger emissions for cross-pattern notification (`UserInformed(...)`)
- Responding to external state transitions (`when: session: oauth/Session.status transitions_to expiring`)
- Using external entities (`oauth/Session`, `stripe/Customer`)
- Linking application entities to external entities (`stripe_customer: stripe/Customer?`)
- Triggering external actions (`ensures: stripe/CreateSubscription(...)`)
- Qualified names throughout (`oauth/Session`, `stripe/config.trial_period`)
### Library Spec Design Principles
When creating or choosing library specs:
1. **Immutable coordinates**: Always use content-addressed references (git SHAs), never floating versions
2. **Configuration over convention**: Library specs should expose configuration for anything that might vary between applications
3. **Observable triggers**: Library specs should emit triggers for all significant events so consuming specs can respond
4. **Minimal coupling**: Library specs shouldn't depend on your application entities - the linkage goes one way
5. **Clear boundaries**: The library spec handles its domain (OAuth flow, payment processing); your spec handles application concerns (user creation, access control)
---
## Pattern 9: Framework Integration Contract
**Demonstrates:** Contract declarations, expression-bearing invariants, `contracts:` clause with `demands`/`fulfils`, programmatic surfaces, typed signatures
This pattern specifies the contract between an event-sourcing framework and its domain modules. The framework demands that each module supply a deterministic evaluation function; in return, the surface fulfils event submission and state snapshot services. Unlike user-facing surfaces that use `exposes` and `provides`, framework-to-module boundaries use a `contracts:` clause with `demands` and `fulfils` to describe programmatic obligations. Contracts are declared at module level so they can be reused across surfaces or referenced from other specs.
```
-- allium: 3
-- event-sourcing-integration.allium
------------------------------------------------------------
-- Value Types
------------------------------------------------------------
value EntityKey {
kind: String
id: String
}
value EventOutcome {
entity_key: EntityKey
new_state: ByteArray
side_effects: List<SideEffect>
}
value SideEffect {
kind: emit_event | schedule_timeout | request_snapshot
payload: ByteArray
}
value SnapshotRequest {
entity_key: EntityKey
as_of: Timestamp
}
value Snapshot {
entity_key: EntityKey
state: ByteArray
version: Integer
taken_at: Timestamp
}
------------------------------------------------------------
-- Contracts
------------------------------------------------------------
contract DeterministicEvaluation {
evaluate: (event_name: String, payload: ByteArray, current_state: ByteArray) -> EventOutcome
@invariant Determinism
-- For identical inputs (event_name, payload, current_state),
-- evaluate must produce byte-identical EventOutcome values
-- across all instances and invocations.
@invariant Purity
-- evaluate must not perform I/O, read the system clock,
-- access mutable state outside its arguments, or depend
-- on the order of previous invocations.
@invariant TotalFunction
-- evaluate must return a valid EventOutcome for every
-- combination of registered event_name, well-formed payload
-- and current_state. It must not throw or fail to terminate.
@guidance
-- Implementations should avoid allocating during evaluation
-- where possible, as the framework may invoke evaluate
-- at high frequency during replay.
}
contract EventSubmitter {
submit: (idempotency_key: String, event_name: String, payload: ByteArray) -> EventSubmission
@invariant AtMostOnceProcessing
-- Within the submission TTL window (config.submission_ttl),
-- a given idempotency key is accepted at most once.
-- Duplicate submissions are rejected.
@invariant OrderPreservation
-- Events submitted by a single module are processed in
-- submission order. No ordering guarantee exists across
-- modules.
}
contract StateSnapshots {
request_snapshot: (entity_key: EntityKey) -> Snapshot
get_snapshot: (request: SnapshotRequest) -> Snapshot?
@invariant SnapshotConsistency
-- A snapshot reflects the state after applying all events
-- up to and including the snapshot's version number.
-- No partial application.
}
------------------------------------------------------------
-- Entities
------------------------------------------------------------
entity DomainModule {
name: String
version: String
status: registered | active | suspended
-- Relationships
event_types: EventTypeRegistration with module = this
-- Projections
active_event_types: event_types where status = active
}
entity EventTypeRegistration {
module: DomainModule
event_name: String
schema_hash: String
status: active | deprecated
registered_at: Timestamp
}
entity EventSubmission {
module: DomainModule
idempotency_key: String
event_name: String
payload: ByteArray
status: pending | accepted
submitted_at: Timestamp
processed_at: Timestamp?
invariant PayloadWithinLimit { length(payload) <= config.max_payload_bytes }
}
------------------------------------------------------------
-- Config
------------------------------------------------------------
config {
submission_ttl: Duration = 24.hours
max_payload_bytes: Integer = 1_000_000
}
------------------------------------------------------------
-- Rules
------------------------------------------------------------
rule RegisterModule {
when: RegisterModule(module_name, version, event_types)
requires: not exists DomainModule{name: module_name}
ensures:
let module = DomainModule.created(
name: module_name,
version: version,
status: registered
)
for event_name in event_types:
EventTypeRegistration.created(
module: module,
event_name: event_name,
schema_hash: hash(event_name + version),
status: active,
registered_at: now
)
}
rule ActivateModule {
when: module: DomainModule.status becomes registered
requires: module.event_types.count > 0
ensures: module.status = active
}
rule SubmitEvent {
when: SubmitEvent(module, idempotency_key, event_name, payload)
let existing = EventSubmission{module: module, idempotency_key: idempotency_key}
requires: module.status = active
requires: not exists existing
requires: exists EventTypeRegistration{module: module, event_name: event_name, status: active}
requires: length(payload) <= config.max_payload_bytes
ensures: EventSubmission.created(
module: module,
idempotency_key: idempotency_key,
event_name: event_name,
payload: payload,
status: pending,
submitted_at: now
)
}
rule ProcessSubmission {
when: submission: EventSubmission.status becomes pending
ensures: submission.status = accepted
ensures: submission.processed_at = now
}
rule ExpireOldSubmissions {
when: submission: EventSubmission.submitted_at + config.submission_ttl <= now
requires: submission.status in {pending, accepted}
ensures: not exists submission
}
rule DeprecateEventType {
when: DeprecateEventType(module, event_name)
let registration = EventTypeRegistration{module: module, event_name: event_name}
requires: exists registration
requires: registration.status = active
ensures: registration.status = deprecated
}
rule SuspendModule {
when: SuspendModule(admin, module, reason)
requires: module.status = active
ensures: module.status = suspended
ensures: AuditLog.created(
event: module_suspended,
timestamp: now,
metadata: { module: module.name, reason: reason, by: admin }
)
}
rule ReactivateModule {
when: ReactivateModule(admin, module)
requires: module.status = suspended
requires: module.event_types.count > 0
ensures: module.status = active
}
------------------------------------------------------------
-- Actor Declarations
------------------------------------------------------------
actor FrameworkRuntime {
identified_by: DomainModule where status = active
}
------------------------------------------------------------
-- Surfaces
------------------------------------------------------------
-- User-facing surface for module administration
surface ModuleAdministration {
facing admin: User
exposes:
for module in DomainModules:
module.name
module.version
module.status
module.active_event_types.count
provides:
RegisterModule(module_name, version, event_types)
for module in DomainModules where status = active:
SuspendModule(admin, module, reason)
for registration in module.active_event_types:
DeprecateEventType(module, registration.event_name)
for module in DomainModules where status = suspended:
ReactivateModule(admin, module)
}
-- Programmatic surface: the framework-to-module integration contract
surface EventSourcingIntegration {
facing runtime: FrameworkRuntime
context module: DomainModule where status = active
contracts:
demands DeterministicEvaluation
fulfils EventSubmitter
fulfils StateSnapshots
@guarantee ModuleBoundaryIsolation
-- Events and state from one module are never visible to
-- another module's evaluate function. Cross-module
-- communication happens only through side effects processed
-- by the framework.
}
```
**Key language features shown:**
- `contract` declarations at module level for reuse across surfaces
- Surface `contracts:` clause with `demands`/`fulfils` direction markers (`demands DeterministicEvaluation`, `fulfils EventSubmitter`) without repeating signatures or invariants
- Expression-bearing `invariant Name { expression }` on entities (`PayloadWithinLimit` on `EventSubmission`)
- Prose-only `@invariant Name` inside contracts for properties that cannot be expressed as a single boolean expression
- `@guarantee Name` at surface level, distinct from contract-scoped invariants (boundary-wide vs contract-scoped assertions)
- `@guidance` inside a contract for non-normative implementation advice
- Mixed surface: `ModuleAdministration` uses traditional `exposes`/`provides` for human actors; `EventSourcingIntegration` uses `contracts:` clause for programmatic integration
- Actor declaration for a code-level party (`FrameworkRuntime` identified by an active module)
### When to use contracts
Use `contract` declarations when the boundary is between code and code rather than between a user and an application. All contracts are declared at module level and referenced in surfaces via a `contracts:` clause with `demands`/`fulfils` direction markers. Common scenarios:
- **Framework-to-plugin contracts**: the framework demands evaluation logic, fulfils lifecycle services
- **Service-to-adapter boundaries**: the service demands a storage adapter, fulfils a query interface
- **Cross-context integration**: one bounded context demands event handlers, fulfils event streams
- **SDK contracts**: the SDK demands configuration and callbacks, fulfils client operations
Do not use contracts for user-facing surfaces. If the external party is a person interacting through a UI, use `exposes` (what they see) and `provides` (what actions they can take). Contracts describe what code must implement, not what users can do.
### Contracts vs provides
`provides:` lists actions that an actor can invoke, each corresponding to a rule's external stimulus trigger. `fulfils ContractName` in a `contracts:` clause declares a set of typed operations that the surface owner supplies to the counterpart as an API. The distinction:
- `provides: SubmitEvent(module, key, name, payload)` — an action the actor triggers; a rule fires in response
- `fulfils EventSubmitter` — a typed operation set the surface makes available, defined in a `contract` declaration; the implementation is the surface owner's responsibility
Both describe things the surface supplies, but `provides` connects to the rule system while `fulfils` references a programmatic contract with typed signatures and invariants.
### Example: Calling an external API (the `demands` side)
The main example above is the surface owner *supplying* services to its counterpart (`fulfils EventSubmitter`). The mirror-image case is just as common, and easy to model wrongly: your spec is the **client** that calls out to an external typed API — a third-party REST service, a vendor SDK, or an MCP server. Reaching for `provides:` here is the wrong turn, because `provides` is for a user triggering a domain rule, not for one body of code calling another. The right construct is a module-level `contract` referenced with `demands` from the caller's surface: the spec requires the counterpart to implement the operations, and calls them.
This example models an address book that resolves postal addresses to coordinates through an external geocoding service. Our spec is purely the caller — it declares the typed boundary and records results, but never implements `geocode` itself.
```
-- allium: 3
-- geocoding-client.allium
------------------------------------------------------------
-- External Entities
------------------------------------------------------------
-- The third-party service we call. Its lifecycle is governed
-- elsewhere; we only model that it sits on the other side of the
-- boundary as the party that implements the API we demand.
external entity GeocodingService {}
------------------------------------------------------------
-- Value Types
------------------------------------------------------------
value Address {
line1: String
city: String
postcode: String
country: String
}
value LatLng {
latitude: Decimal
longitude: Decimal
}
value GeocodeResult {
location: LatLng
formatted_address: String
confidence: Decimal -- 0.0 (no match) to 1.0 (exact match)
}
------------------------------------------------------------
-- Contracts
------------------------------------------------------------
-- The typed boundary of the external geocoding API. Our spec is
-- the client: it calls these operations, it does not implement them.
contract GeocodingApi {
geocode: (address: Address) -> GeocodeResult?
reverse_geocode: (location: LatLng) -> GeocodeResult?
@invariant ReadOnly
-- geocode and reverse_geocode never mutate remote state.
-- A call with identical arguments is safe to retry and
-- yields an equivalent result.
@invariant NullOnNoMatch
-- When the provider finds no location for the input, the
-- operation returns null rather than a zero-confidence
-- result or an error.
@guidance
-- The provider rate-limits per API key. Callers should
-- debounce lookups triggered by partial address entry.
}
------------------------------------------------------------
-- Entities
------------------------------------------------------------
entity Place {
label: String
address: Address
status: unresolved | resolved | unlocatable
-- Populated from a successful GeocodingApi.geocode result
location: LatLng?
resolved_at: Timestamp?
}
------------------------------------------------------------
-- Rules
------------------------------------------------------------
rule RecordGeocodeResult {
when: GeocodeResolved(place, result)
requires: place.status = unresolved
ensures: place.location = result.location
ensures: place.status = resolved
ensures: place.resolved_at = now
}
rule RecordGeocodeMiss {
when: GeocodeNotFound(place)
requires: place.status = unresolved
ensures: place.status = unlocatable
}
------------------------------------------------------------
-- Surfaces
------------------------------------------------------------
-- Programmatic surface: our spec is the CALLER of the external API.
-- `demands` declares that we require the counterpart (the geocoding
-- service we face) to implement GeocodingApi; we do not supply it.
surface GeocodingClient {
facing provider: GeocodingService
contracts:
demands GeocodingApi
@guarantee NoUnresolvedWrites
-- A Place only stores a location obtained from a successful
-- GeocodingApi.geocode call; an unlocatable address never
-- receives coordinates.
}
```
Like the framework example, the rules handle domain state (recording a result) rather than spelling out the call itself — the `contract` declares the typed boundary, and `demands` on the surface records who must implement it.
**Reading the direction markers.** The choice between `demands`, `fulfils` and `provides` is about who implements what, and for whom:
- `demands GeocodingApi` — *I call out to the counterpart.* The facing party implements these operations; my spec invokes them. Use for "my spec is a client of an external API/SDK/MCP server".
- `fulfils EventSubmitter` — *I supply this API to the counterpart.* My spec implements these operations; the facing party invokes them. Use for "my spec is the service others integrate against" (as in the framework example above).
- `provides UserResetsPassword(...)` — *a user triggers an action and a domain rule fires.* Not a code-to-code contract at all; the action maps to a rule's external stimulus trigger. Use for human-facing surfaces.
A single surface can mix `demands` and `fulfils` (the framework demands evaluation logic while fulfilling submission and snapshot services). It should not use a `contracts:` clause and `provides:` to describe the *same* boundary: `provides` is for people, `demands`/`fulfils` for code.
### Invariant vs guarantee
`@guarantee` asserts a property of the surface boundary as a whole. `invariant` asserts a property scoped to the operations within a specific contract.
Invariants come in two forms. Expression-bearing invariants carry a boolean expression that can be checked mechanically. Prose invariants describe properties that require human or LLM judgement.
```
-- Expression-bearing invariant on an entity
entity EventSubmission {
...
invariant PayloadWithinLimit { length(payload) <= config.max_payload_bytes }
}
-- Prose invariant inside a contract
contract DeterministicEvaluation {
@invariant Purity
-- evaluate must not perform I/O or access mutable state.
}
-- Surface-level guarantee: applies across the entire boundary
@guarantee ModuleBoundaryIsolation
-- Events from one module are never visible to another module.
```
Use `@guarantee` for cross-cutting properties that span the whole surface. Use `invariant` for properties tied to specific operations within a contract, or for entity-level assertions.
---
## Using These Patterns
### Composition
Patterns can be composed. For example, a complete document collaboration spec might use:
```
use "./rbac.allium" as rbac
use "./soft-delete.allium" as trash
use "./comments.allium" as comments
use "./notifications.allium" as notify
entity Document {
workspace: Workspace
title: String
content: String
status: active | deleted
deleted_at: Timestamp?
deleted_by: User?
-- From comments pattern
comments: comments/Comment with document = this
-- From soft-delete pattern
retention_expires_at: deleted_at + trash/config.retention_period
can_restore: status = deleted and retention_expires_at > now
...
}
-- Document actions require RBAC checks
rule EditDocument {
when: EditDocument(user, document, content)
let share = rbac/ResourceShare{resource: document, user: user}
requires: share.can_edit
...
}
```
### Adaptation
Patterns are starting points. When applying:
1. **Rename** to match your domain (User → Member, Document → Note)
2. **Adjust** timeouts and limits to your context
3. **Remove** unused states or rules
4. **Extend** with domain-specific behaviour
5. **Compose** multiple patterns for richer functionality
### Anti-Patterns
When using patterns, avoid:
- **Over-engineering**: Don't include reaction system if you don't need reactions
- **Premature abstraction**: Start concrete, extract patterns when you see repetition
- **Pattern worship**: If the pattern doesn't fit, adapt it or write something custom
- **Ignoring context**: A free tier pattern that makes sense for B2C may not fit B2B
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |