adachsoft/agent-rule-contract

Contract-only PHP library for agent rule definitions (enums, DTOs, collections, exceptions and interfaces) in the AdachSoft AI ecosystem.

v0.2.0 2026-02-06 21:56 UTC

Requires

• php: ^8.3
• adachsoft/collection: ^3.0

Requires (Dev)

• adachsoft/php-code-style: ^0.2
• friendsofphp/php-cs-fixer: ^3.89
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.4
• rector/rector: ~2.3.3

MIT

• Arkadiusz Adach

• php
• rules
• Agent
• ai
• contracts
• adachsoft

README

Contract-only PHP library defining enums, DTOs, collections, exceptions and interfaces for agent rule management in the AdachSoft AI ecosystem.

Installation

composer require adachsoft/agent-rule-contract

Overview

This package provides stable contracts for building rule-aware agents:

• enums describing rule type, scope and target,
• immutable rule data transfer object (RuleDto),
• immutable rule collection (RuleCollection),
• domain exceptions for the rule subsystem,
• interfaces for rule registry, rule provider, rule conflict resolver and rule writer.

The library does not ship any runtime implementation of storage or rule evaluation. It is intended to be consumed by higher-level components that implement these interfaces.

Enums

• RuleTypeEnum – describes the normative nature of a rule:
  • REQUIREMENT – something the agent must do,
  • PROHIBITION – something the agent must not do,
  • GUIDELINE – soft recommendation or best practice,
  • CONSTRAINT – hard technical or business constraint.
• RuleScopeEnum – describes the scope in which a rule applies:
  • GLOBAL – shared across all projects,
  • PROJECT – scoped to a specific project.
• RuleTargetEnum – describes what the rule targets:
  • AGENT – agent behaviour in general,
  • TOOL – usage of external tools,
  • CODE – source code generation or modification,
  • OUTPUT – final responses / visible output.

These enums are part of the public contract and should be used consistently across all rule-related components.

Rule DTO

AdachSoft\AgentRuleContract\Dto\RuleDto is a readonly immutable data transfer object representing a single rule:

• id (string) – stable identifier of the rule (unique within your system),
• type (RuleTypeEnum) – semantic type of the rule,
• scope (RuleScopeEnum) – scope where the rule applies,
• target (RuleTargetEnum) – primary target of the rule,
• content (string) – human- or machine-readable rule content,
• priority (int) – optional priority used by consumers to order or select rules (default 0),
• metadata (KeyedCollectionInterface<string, mixed>|null) – optional key-value collection with additional data (e.g. tags, origin, audit information).

Consumers should treat RuleDto as an immutable snapshot and avoid mutating any referenced metadata collections in-place.

Rule collection

AdachSoft\AgentRuleContract\Collection\RuleCollection is an immutable collection of RuleDto instances. It:

• guarantees that all items are instances of RuleDto,
• provides value-object style behaviour (no in-place modifications),
• can be safely passed between layers and components.

Interfaces

The following interfaces define the integration points for your application:

• RuleRegistryInterface – central entry point for obtaining rules:
  • getGlobalRules(): RuleCollection – returns rules that apply in all projects,
  • getProjectRules(string $projectId): RuleCollection – returns rules specific to a given project,
  • resolveEffectiveRules(string $projectId): RuleCollection – returns the final, resolved set of rules for a project (after applying conflict resolution and precedence rules, if any).
• RuleProviderInterface – lower-level provider returning RuleCollection for a single project (e.g. backed by database, configuration files or APIs).
• RuleConflictResolverInterface – responsible for resolving conflicts between rules:
  • resolve(RuleCollection $rules): RuleCollection – returns a new collection with conflicts resolved according to your domain logic.
• RuleWriterInterface (since v0.2.0) – responsible for creating, updating and deleting rules, as well as checking their existence in the underlying storage.

Implementations of these interfaces live in your application or infrastructure code and are outside the scope of this package.

Exceptions

The library exposes a small hierarchy of domain exceptions:

• RuleException – base exception for all rule-related errors (extends RuntimeException),
• RuleRegistryException – errors related to the rule registry (e.g. lookup, configuration),
• RuleResolutionException – errors related to building or resolving the effective rule set.

These exceptions can be used by your implementations of the interfaces to signal domain-specific error conditions in a consistent way.

Usage

In your project:

• implement AdachSoft\AgentRuleContract\Contract\RuleRegistryInterface,
• optionally implement AdachSoft\AgentRuleContract\Contract\RuleProviderInterface and AdachSoft\AgentRuleContract\Contract\RuleConflictResolverInterface,
• implement AdachSoft\AgentRuleContract\Contract\RuleWriterInterface if you need to create, update or delete rules in your storage,
• build rules as RuleDto instances and expose them as RuleCollection from your implementations.

A simple example flow:

1. RuleProviderInterface implementation loads raw rule definitions from your storage.
2. It converts them into RuleDto objects and returns them wrapped in a RuleCollection.
3. RuleRegistryInterface aggregates global and project-specific rules, optionally calls RuleConflictResolverInterface to handle conflicts, and exposes the final RuleCollection to downstream components (e.g. agents, tools, orchestrators).
4. RuleWriterInterface is used by your application code to create, update or delete rules, and to check their existence before operations.