diff --git a/llms-full.txt b/llms-full.txt new file mode 100644 index 0000000..3bfde49 --- /dev/null +++ b/llms-full.txt @@ -0,0 +1,347 @@ +# Be Framework - Full Documentation + +> Objects don't DO things—they BECOME things. + +Be Framework is a PHP framework for ontological programming where transformation (metamorphosis) replaces procedural action. + +## Core Philosophy + +A patient doesn't "get triaged." They **become** an emergency case or an observation case, based on the transcendent wisdom of medical protocol. + +## Key Concepts + +### Domain Ontology (Semantic Variables) + +Semantic variables define what CAN exist in a domain—not just validation rules, but the vocabulary of existence. This declarative foundation serves as documentation that both humans and AI can read to understand your domain. + +```php +final class BodyTemperature +{ + #[Validate] + public function validate(float $bodyTemperature): void + { + if ($bodyTemperature < 30.0 || $bodyTemperature > 45.0) { + throw new LethalVitalException(); + } + } +} +``` + +### Reason (Transcendence) + +Domain logic becomes a first-class citizen: injectable, testable, and explicitly visible. + +```php +final readonly class JTASProtocol +{ + /** @return 'emergency'|'observation' */ + public function assess(float $bodyTemperature, int $heartRate): string + { + if ($bodyTemperature >= 39.0 || $heartRate >= 120) { + return 'emergency'; + } + return 'observation'; + } +} +``` + +### Metamorphosis Pattern + +Input → Being → Final transformation through the Becoming class. + +```php +$becoming = new Becoming($injector, 'Be\\App\\Semantic'); +$patient = new PatientArrival(bodyTemperature: 39.5, heartRate: 90); +$result = $becoming($patient); +// $result IS an EmergencyCase or ObservationCase +``` + +### Type-Driven Branching + +The `$being` property (Union type) determines which Final class receives the transformation. + +```php +#[Be([EmergencyCase::class, ObservationCase::class])] +final readonly class TriageAssessment +{ + public Emergency|Observation $being; + + public function __construct( + #[Input] public float $bodyTemperature, + #[Input] public int $heartRate, + #[Inject] JTASProtocol $protocol + ) { + $urgency = $protocol->assess($bodyTemperature, $heartRate); + $this->being = ($urgency === 'emergency') + ? new Emergency() + : new Observation(); + } +} +``` + +### Type IS Capability + +Different Final types have different methods—the type determines what actions are possible. + +```php +// EmergencyCase has assignER() +// ObservationCase has assignWaitingArea() +$result->assignER(); // Only possible for EmergencyCase +``` + +## Key Attributes + +- `#[Be([TargetClass::class])]` - Declares metamorphosis destination(s) +- `#[Input]` - Receives data from previous stage +- `#[Inject]` - Receives transcendent capability (DI) +- `#[Validate]` - Semantic validation method marker + +## Domain Types (PHPDoc Union Types) + +Use PHPDoc union types to define domain vocabulary: + +```php +final readonly class JTASProtocol +{ + /** @return 'emergency'|'observation' */ + public function assess(float $bodyTemperature, int $heartRate): string + { + // ... + } +} + +final readonly class EmergencyCase +{ + /** @var 'IMMEDIATE'|'DELAYED' */ + public string $priority; + /** @var 'RED'|'GREEN' */ + public string $color; +} +``` + +This makes the domain vocabulary explicit and enables static analysis tools (Psalm, PHPStan) to catch invalid values. + +## Naming Conventions + +### Semantic Variables + +Semantic class name matches constructor parameter name (camelCase): + +- `BodyTemperature` class validates `$bodyTemperature` parameter +- `HeartRate` class validates `$heartRate` parameter + +### Destiny Markers and Final Classes + +Final class receives the destiny marker matching its `#[Input]` type: + +```php +// Destiny markers (empty classes that ARE the distinction) +final readonly class Emergency {} +final readonly class Observation {} + +// Final classes receive matching destiny via #[Input] +final readonly class EmergencyCase +{ + public function __construct( + #[Input] public Emergency $being // Receives Emergency marker + ) {} +} + +final readonly class ObservationCase +{ + public function __construct( + #[Input] public Observation $being // Receives Observation marker + ) {} +} +``` + +## Transformation Flow + +### With Branching (Input → Being → Final) + +``` +Input (with #[Be([Being::class])]) + ↓ Becoming executes +Being (with #[Be([Final1::class, Final2::class])]) + ↓ $being property determines branch +Final (capability-specific type) +``` + +### Direct (Input → Final) + +When no branching is needed, Input can transform directly to Final: + +```php +#[Be([Hello::class])] +final readonly class HelloInput +{ + public function __construct(public string $name) {} +} + +final readonly class Hello +{ + public function __construct( + #[Input] public string $name, + #[Inject] Greeting $greeting + ) {} +} +``` + +## Error Handling + +When semantic validation fails, metamorphosis is rejected: + +```php +try { + $becoming($input); +} catch (SemanticVariableException $e) { + $messages = $e->getErrors()->getMessages('en'); + // ["Vital signs indicate non-survivable conditions."] +} +``` + +## Project Structure + +``` +src/ +├── Input/ # Starting points (raw data) +├── Being/ # Intermediate transformations +├── Final/ # Destinations (capability-specific types) +├── Reason/ # Transcendent wisdom (domain logic) +├── Semantic/ # Domain ontology (what CAN exist) +├── Exception/ # Domain exceptions +└── Module/ # DI configuration +``` + +## Example: Emergency Triage + +### Input Class + +```php +#[Be([TriageAssessment::class])] +final readonly class PatientArrival +{ + public function __construct( + public float $bodyTemperature, + public int $heartRate + ) {} +} +``` + +### Being Class + +```php +#[Be([EmergencyCase::class, ObservationCase::class])] +final readonly class TriageAssessment +{ + public Emergency|Observation $being; + + public function __construct( + #[Input] public float $bodyTemperature, + #[Input] public int $heartRate, + #[Inject] JTASProtocol $protocol + ) { + $urgency = $protocol->assess($bodyTemperature, $heartRate); + $this->being = ($urgency === 'emergency') + ? new Emergency() + : new Observation(); + } +} +``` + +### Final Classes + +```php +final readonly class EmergencyCase +{ + /** @var 'IMMEDIATE'|'DELAYED' */ + public string $priority; + /** @var 'RED'|'GREEN' */ + public string $color; + + public function __construct( + #[Input] public float $bodyTemperature, + #[Input] public int $heartRate, + #[Input] public Emergency $being + ) { + $this->priority = 'IMMEDIATE'; + $this->color = 'RED'; + } + + public function assignER(): string + { + return "Secure ER Room 1 immediately."; + } +} + +final readonly class ObservationCase +{ + /** @var 'IMMEDIATE'|'DELAYED' */ + public string $priority; + /** @var 'RED'|'GREEN' */ + public string $color; + + public function __construct( + #[Input] public float $bodyTemperature, + #[Input] public int $heartRate, + #[Input] public Observation $being + ) { + $this->priority = 'DELAYED'; + $this->color = 'GREEN'; + } + + public function assignWaitingArea(): string + { + return "Move to waiting area."; + } +} +``` + +### Execution + +```php +$injector = new Injector(new AppModule()); +$becoming = new Becoming($injector, 'Be\\App\\Semantic'); + +$patient = new PatientArrival(bodyTemperature: 39.5, heartRate: 90); +$result = $becoming($patient); + +echo $result->priority; // "IMMEDIATE" +echo $result->assignER(); // "Secure ER Room 1 immediately." +``` + +## Why Being Over Doing + +### Traditional (Doing) + +```php +$patient = new Patient($temp, $hr); +if ($triageService->isEmergency($patient)) { + $patient->setStatus('emergency'); + $this->erService->assign($patient); +} +``` + +Problems: +- Patient can exist in invalid state +- Status can be changed at any time +- `erService->assign()` can be called on any patient + +### Be Framework (Being) + +```php +$patient = new PatientArrival($temp, $hr); +$result = $becoming($patient); +$result->assignER(); // Type-safe: only possible for EmergencyCase +``` + +Benefits: +- Non-survivable states cannot exist +- Type IS the status (immutable) +- Capabilities belong to existence + +## Documentation + +- English: https://be-framework.github.io/manuals/1.0/en/ +- Japanese: https://be-framework.github.io/manuals/1.0/ja/ +- Repository: https://github.com/be-framework/be-framework diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..92689f6 --- /dev/null +++ b/llms.txt @@ -0,0 +1,25 @@ +# Be Framework + +> Objects don't DO things—they BECOME things. + +Be Framework is a PHP framework for ontological programming where transformation (metamorphosis) replaces procedural action. + +## Documentation + +- [Overview](https://be-framework.github.io/manuals/1.0/en/01-overview.html): Framework philosophy +- [Getting Started](https://be-framework.github.io/manuals/1.0/en/getting-started.html): Quick start guide +- [Tutorial](https://be-framework.github.io/manuals/1.0/en/tutorial.html): Emergency Triage example +- [Input Classes](https://be-framework.github.io/manuals/1.0/en/02-input-classes.html): Starting points +- [Being Classes](https://be-framework.github.io/manuals/1.0/en/03-being-classes.html): Intermediate transformations +- [Final Objects](https://be-framework.github.io/manuals/1.0/en/04-final-objects.html): Destinations +- [Semantic Variables](https://be-framework.github.io/manuals/1.0/en/06-semantic-variables.html): Domain validation +- [Type-Driven Metamorphosis](https://be-framework.github.io/manuals/1.0/en/07-type-driven-metamorphosis.html): Branching patterns +- [Reason Layer](https://be-framework.github.io/manuals/1.0/en/08-reason-layer.html): Transcendence + +## Full Documentation + +For detailed API and examples, see [llms-full.txt](https://be-framework.github.io/llms-full.txt) + +## Repository + +https://github.com/be-framework/be-framework diff --git a/manuals/1.0/en/faq.md b/manuals/1.0/en/faq.md index 93a027d..76b7615 100644 --- a/manuals/1.0/en/faq.md +++ b/manuals/1.0/en/faq.md @@ -269,7 +269,21 @@ A mechanism for holding failures and history not as simple strings, but as struc --- -## 11) Related Chapter Links +## 11) Using AI Agents + +### Q27. How do I get AI to write Be Framework code? + +A. Simply ask the AI to read the llms-full.txt: + +``` +Please read https://be-framework.github.io/llms-full.txt +``` + +This file contains all the key concepts, naming conventions, and code examples needed for AI to understand and generate Be Framework code. + +--- + +## 12) Related Chapter Links * **[Overview](./01-overview.html)**: First encounter with being-oriented programming * **[Metamorphosis](./05-metamorphosis.html)**: Inseparability of time and domain diff --git a/manuals/1.0/ja/faq.md b/manuals/1.0/ja/faq.md index 3973902..d08db44 100644 --- a/manuals/1.0/ja/faq.md +++ b/manuals/1.0/ja/faq.md @@ -296,7 +296,21 @@ $profile = $becoming(new UserInput($name, $email)); --- -## 11) 関連章へのリンク +## 11) AIエージェントの活用 + +### Q27. AIにBe Frameworkのコードを書かせるにはどうすればいいですか? + +A. AIにllms-full.txtを読むよう依頼するだけです: + +``` +https://be-framework.github.io/llms-full.txt を読んでください +``` + +このファイルには、AIがBe Frameworkを理解しコードを生成するために必要な、主要概念、命名規則、コード例がすべて含まれています。 + +--- + +## 12) 関連章へのリンク * **[概要](./01-overview.html)**: 存在指向プログラミングとの出会い * **[変容](./05-metamorphosis.html)**: 時間とドメインの不可分性