MortelOS Framework

mortelos/framework is the core library for MortelOS primitives and runtime behavior.

The current PHP namespace can still be Mortel\... during the external package naming transition. Use mortelos/framework as the public package name in docs, plans and package decisions.

Use It For

Install

composer require mortelos/framework

Packages resolve from the MortelOS registry. Configure registry access once before installing; see Installation.

Upgrading to 0.7.0

Version 0.7.0 renames every Dutch name in the framework to English: classes, methods, tables, columns, config keys, event properties and stored values. There are no aliases for the old names. Stay on ^0.6 until your app is ready; 0.6.x keeps receiving fixes.

What an app must do:

1. Require mortelos/framework:^0.7. Update the packages that depend on it at the same time: chat, overviews, widget-compliance, the starter and the channel packages move together.

2. Publish the new migration and run it. Publishing does not overwrite the migrations you already have. It only adds the new file.

   php artisan vendor:publish --tag=os-core-migrations
   php artisan migrate            # or tenants:migrate, where your framework migrations live
   

   The migration 2026_10_16_000001_rename_dutch_schema_names_to_english renames the tables, columns and indexes below and rewrites the stored Dutch values. It only renames what still has its old name, so it is safe to run twice and does nothing on a fresh install. It is one-way: down() does nothing. Take a backup first.

3. If you published config/mortel.php, rename inbox.max_per_bron_per_dag to inbox.max_per_source_per_day.

4. Rename every name from the tables below in your own code, views and tests.

Database

The migration also rewrites these stored values:

The migration does not rewrite two things. Customer entities imported from a vault before 0.7 keep klant_number in their attributes, and nothing in the framework reads it. Import them again to get customer_number. A tenant AI setting that stores the preset snel or diep as text falls back to medium. Set it to fast or deep.

PHP

The vault frontmatter now reads customer-number, customer-name, customer, start-date and phase. It still recognises the Dutch klant-nr, klant-naam, klant, startdatum and fase.

AI contracts

• The classification prompt asks for quote instead of bronpassage, and for the types decision, fact, action and context instead of beslissing, feit, actie and context.
• The platform.usage agent tool takes days instead of dagen. It returns period_days, logins_recorded_since and users with name, email, last_login, logins_in_period, last_chat_question, chat_questions_in_period and chat_questions_total.

Events other packages listen to

• Mortel\Events\Inbox\InboxBronAfgeremd is now InboxSourceThrottled. Rename your listeners.
• The Livewire browser event overzicht-saved is now overview-saved. The framework does not dispatch it. mortelos/overviews sends it, and mortelos/chat and the starter listen to it, so upgrade those three together.

Outlets

An outlet is a place where you extend mortelos/framework from your app without changing the package. The table lists the outlets in its resources/mortelos/outlets.json as of version 0.7.0; read Outlets for how each kind works and what to do when none fits.

php artisan mortelos:outlets:list framework

Writing a tenant setting checks the gate ability tenant-settings.write; define it in the host. A gate is not an outlet in the manifest.

Boundaries

Use this package for OS-level primitives that multiple MortelOS installations can share. Keep customer-specific policy defaults, branding, local orchestration and one-off integrations in the host app.

Action results, undo and actors

Since v0.6.38 every write goes through the same few types. The starter shows them in use: app/Actions/Invitations/InviteUser.php and app/Providers/StarterServiceProvider.php.

• Mortel\Actions\ActionResult is what an Action returns. Its status is done, approval_needed, failed or skipped. A refusal by policy stays an exception.
• Mortel\Actions\Undo is the recipe to reverse a change: a counter-Action class, its params and a validUntil. It lives in the result, not in the event.
• Mortel\Actions\UndoRegistry maps a counter-Action to its handler. The counter-Action records its own event, and that event is the audit.
• Mortel\Support\Actor says who acts, in four forms: Actor::user() (the bare user id), Actor::agent() (agent:<run-id>), Actor::system() (system:<process>) and Actor::bridge() (bridge:<name>).
• EventContext::within($actor, $reason, $work) fills actor, reason, org and branch around the work and restores the previous context afterwards.
• PolicyScope::Action is the policy scope of host Action abilities such as invitations.manage.
• config('mortel.events.schema_namespaces') opts a host namespace in to payload validation. The schema file sits next to the event class, and its name follows the class name: InvitationCreated is validated against invitation.created.v1.schema.json.
• handle() is the method on every Action. execute() still works on the Actions that had it.
• The events.actor column is 255 characters wide from v0.6.41, so agent:, system: and bridge: actors fit.

Future Optimization Notes

When MortelOS optimization work moves from application-level cleanup to database-level tuning, consider PostgreSQL functions or procedures for small, data-heavy invariants. Good candidates are planner task ordering, append-to-day task planning, entity search ranking, memory recall candidate lookup, import-registry claims, AI action statistic increments and version publication counters.

Do not move broad workflows into the database by default. Keep external API calls, AI calls, embeddings, queue dispatch, Laravel events, mail delivery, policy orchestration and UI behavior in application code. Database routines should only own logic that benefits from atomicity, indexes, locking or reduced round trips.

Runtime mount

Host apps mount the framework MCP server when operate mode is enabled:

use Laravel\Mcp\Facades\Mcp;
use Mortel\MCP\Servers\UteqOSServer;

Mcp::oauthRoutes();

Mcp::web('/mcp/mortelos', UteqOSServer::class)
    ->middleware(['auth:api']);

Production hosts add tenant initialization, role resolution, trust-level enforcement, data classification and throttling around that route.