Declarative
Attributes, JSON Schema, Links, Embeds, Cacheable, and more declare application meaning in code. AI can ground itself in declared meaning rather than guessing hidden conventions.
AI-ready architecture
Toward applications AI doesn't have to guess about.
When AI agents read, modify, and explain code, meaning that remains in the code matters more than ambiguous conventions. BEAR.Sunday preserves application meaning as resources, attributes, schemas, and links.
Explicit
onGet / onPost, constructor injection, DbQuery, and context modules make inputs, dependencies, and runtime configuration explicit. The scope of review extends beyond the inside of a single function.
Traceable
URIs, resources, links, schemas, and documentation all connect to the same model. Trace the impact of changes from implementation all the way to API docs and llms.txt.
Strict types
Built on high static analysis levels from PHPStan and Psalm, meaning is carried not as bare arrays but as shaped arrays, domain arrays, and domain types. Types themselves become AI context.
Design principles for AI
Design principles become AI's decision material.
BEAR.Sunday is not a framework for brandishing names like Clean Architecture, CQS/CQRS, or DDD. But the dependency direction, read/write separation, and business vocabulary boundaries that those approaches have emphasized become powerful clues in an era where AI makes change decisions.
The essence of Clean Architecture
Dependency direction is controlled by interfaces and DI modules. The framework, DB, HTML, API, CLI, and caching are external details. AI can read what is application meaning and what are replaceable details as separate concerns.
The essence of CQS / CQRS
It extracts only the core: optimal models differ between reads and writes. SQL defines projections; PHP adds types and behavior to read models that are disposable. State changes and invariants can be reasoned about as the responsibility of the command/write path.
The essence of DDD
URIs, Resources, interfaces, domain types, and namespaces leave business vocabulary and boundaries in the code. Not a heavy ritual—ubiquitous language and bounded context clues become readable to both AI and humans.
Explicit contracts
Contracts and information structures that AI can read.
Ray.MediaQuery doesn't hide SQL behind object abstractions. Interfaces show the contract, SQL files show the projection, and return types show how results are handled. AI assistants don't have to reverse-engineer hidden query generation. Relationships between resources are also declared as Links, Embeds, crawls, and URIs, so information structure can be traced from the implementation.
Interface becomes the contract
A DbQuery interface shows what the application is asking for. Callers can depend on the method signature and return type rather than how SQL is assembled.
SQL becomes the projection
JOINs, CTEs, window functions, aggregations, and screen-specific columns are explicit as SQL files, not hidden query generation. AI can read what actually executes.
Return types signal intent
Row lists, single rows, hydrated objects, void, AffectedRows, pagination, custom wrappers—the return type declares the intent: fetch, hydrate, wrap, or ignore.
Read models can be tested in small units
SQL, factories, domain objects, and application can be verified layer by layer. Application tests can fake interfaces with typed return values and focus on use cases.
Embed / crawl declares information structure
Related content structure is declared with Links, Embeds, crawl names, and app:// URIs. AI can trace the resource graph left in the implementation rather than guessing relationships by observing HTML.
Tool-ready resources
Resources become AI instruments as-is.
BEAR.ToolUse generates Tool Use definitions for AI agents from BEAR.Sunday ResourceObjects. Meaning expressed through URIs, JSON Schema, ALPS, PHPDoc, and attributes becomes AI-executable instruments. It doesn't depend on any specific LLM—it composes the agent loop as an application-side interface.
Generate Tool definitions from ResourceObjects
JSON Schema-based tool definitions can be generated from existing resource classes. Rather than building separate function sets for AI, the application's actual capabilities become instruments.
Specify usable features by URI
Select resources to expose by URI—app://self/user, page://self/search, etc. #[Tool] and #[Exclude] leave the scope of AI-accessible features in the code.
Descriptions come from the implementation
Parameter descriptions and constraints are assembled from JSON Schema, PHPDoc, and ALPS profiles. AI reads implementation-connected descriptions rather than guessing inputs.
Confirmation gates for destructive operations
Tools with confirm require human approval before execution. Streaming Agents return confirmation events and default to rejection if no response arrives—safe by default.
Filter large results before passing
Filters can summarize tool results before passing them to the LLM. Pass only the needed fields from large search results or lists, preserving token efficiency and information design.
Auditable invocations
ToolCallObserver can observe dispatches including successes, errors, exceptions, and unknown tools. Audit logs, metrics, and latency measurement can be implemented in the application's own context.
REST semantics as a safety model
REST semantics directly become the AI safety model.
Resources can become instruments not because new mechanisms were bolted on. It's because URIs, uniform interface, types, JSON Schema, and ALPS already have the shape of tool definitions. And REST's long-standing method semantics—safe and idempotent—provide the rationale for deciding what agents can freely call and what requires confirmation. BEAR.ToolUse expands from single tool invocations to a runtime that orchestrates specialized agents.
Safe operations freely, dangerous ones with confirmation
Let agents freely call safe, idempotent operations like GET, and gate state-changing operations with confirm. REST method classification directly becomes the tool permission model.
ALPS turns meaning into filters
From safe/idempotent transition information in ALPS profiles, you can narrow the tools passed at runtime. Read-only mode can be derived from resource semantics, not ad-hoc decisions.
Agents traverse the resource graph
In the same structure that hypermedia lets clients follow links, agents traverse URIs and links to investigate and operate. The resource graph directly becomes the agent's map.
Delegate to specialized agents
A coordinator can call specialized agents like ask_critic or ask_editor as tools. Different-role specialists—design review and copy editing—can be orchestrated.
Persist context across invocations
Maintain conversation history across multiple executions, allowing multi-stage workflows of investigation, review, and revision to proceed without rebuilding context each time.
Per-execution policy variation
Narrow the list of provided tools per execution. Apply read-only, cost caps, and safety policies without changing the agent itself.
Explicit context
Explicit context over training volume.
In the AI era, some say more popular frameworks have an advantage. But more public code doesn't directly mean more correct context. Extracting average shapes from a corpus that mixes different versions, quality levels, and design decisions doesn't necessarily lead to clean changes.
What BEAR.Sunday provides to AI is not ambiguous conventions but explicit context connected to the implementation. Interfaces, types, URIs, Links, Schemas, Modules, and generated documentation become the grounding AI needs for reasoning.
Training volume is no substitute for context
Popular frameworks have lots of public code. But that corpus mixes different versions, design philosophies, and quality levels. AI picking up average patterns doesn't guarantee the right judgment for your current application.
From searchable knowledge to actionable context
Stack Overflow-style collective wisdom had great value in an era of hunting for implementation fragments. In the AI era, what matters more than external fragments is whether the codebase in front of you provides enough grounding for AI to reason correctly.
Explicitness aids clean code
In BEAR.Sunday, interfaces, ResourceObjects, Modules, JSON Schema, API docs, and llms-full.txt become explicitly designed information for AI to read. Code can be assembled from implementation-connected evidence, not guesswork.
Locality lowers reasoning cost
DI makes dependencies visible in constructors and Modules. Responsibilities are divided among Resource, Query, and Interceptor. Without having to read a massive whole picture, it's easier to make judgments from the local context of what's being changed.
Agent workflow
Readable units enable delegating changes.
What's hard for AI isn't the volume of code—it's meaning being scattered across multiple places. In BEAR.Sunday, you can trace related information starting from a resource, so the procedure for investigation and change remains stable.
- 01Discover target features from Resource URIs
- 02Read onGet / onPost inputs and outputs
- 03Check types and shapes via PHPStan / Psalm
- 04Check DbQuery interface and SQL file projections
- 05Trace resource graphs declared by Link / Embed / crawl
- 06Check tools and confirmation conditions exposed by BEAR.ToolUse
- 07Check representation contracts via JSON Schema
- 08Check runtime differences via DI modules
- 09Reflect change impact into tests and documentation
Strict types
Strict types strengthen explicitness and locality.
In code that AI modifies, ambiguous arrays and implicit structures become room for guesswork. BEAR.Sunday uses PHPStan and Psalm at high static analysis levels, giving even arrays meaning as shapes and domain types. Types are not just checks—they are specifications for AI to read.
/**
* @phpstan-type UserRow array{id: positive-int, name: non-empty-string}
* @psalm-type UserRow array{id: positive-int, name: non-empty-string}
*/
interface UserQuery
{
/** @return UserRow */
public function item(int $id): array;
}- Use shaped arrays and domain types instead of bare arrays to make representation shapes explicit
- Catch ambiguous value mixing early with PHPStan and Psalm at high static analysis levels
- Connect interfaces, PHPDoc, and JSON Schema to align vocabulary across implementation, tests, and documentation
- When AI completes code, types and shapes narrow the input, output, and scope of change
LLM documentation
llms.txt is the entry point for AI.
API Doc, OpenAPI, JSON Schema, and llms-full.txt are connection points for making the application readable not just to humans but to AI. What matters is that documentation doesn't become isolated from the implementation.
#[JsonSchema(schema: 'user.json')]
#[Link(rel: 'orders', href: 'app://self/orders{?id}')]
public function onGet(int $id): static
{
$this->body = $this->userQuery->item($id);
return $this;
}Start with one resource