Policy Architecture Pattern

Context

The FlexGalaxy.AI platform hosts multiple applications from different developers, each with its own domain logic, constraints, and operational preferences. At the same time, the platform must enforce safety limits and physical constraints that no application should be able to override.

Hardcoding behavior into services is too rigid — a warehouse application and a cleaning application have very different failure recovery needs, scheduling preferences, and operational rules. But allowing applications to define arbitrary behavior is too dangerous — a misconfigured policy could cause a robot to operate unsafely.

The platform needs a policy model that is:

1. Hierarchical — platform safety rules always win

2. Domain-aware — applications can define policies in their own vocabulary

3. Operator-customizable — end users can tune behavior without writing code

4. Validated — every policy is checked for conflicts and safety violations before activation

Pattern

Policy Hierarchy

Policies are organized in three tiers with strict precedence:

Platform defaults (safety, physics, hard limits) — cannot be overridden
    ↓
App-defined policies (developer presets) — can be customized within bounds
    ↓
User-defined policies (via AI Policy Agent) — validated before activation

Tier	Author	Override Rules	Examples
Platform	FlexGalaxy.AI	Cannot be overridden by any lower tier	Minimum battery threshold, maximum speed limits, physics constraints
App-defined	Developer	Customizable by operators within bounds set by the developer	Default failure recovery strategy, scheduling preferences, priority rules
User-defined	Operator (via AI Policy Agent)	Validated against all higher tiers before activation	Custom time-of-day restrictions, zone rules, device-specific overrides

Policy Evaluation

Every decision-making service in the Intelligence Plane consults the Policy Service before acting:

Service (e.g., Scheduler)              Policy Service
         │                                    │
         │  "Can Robot A run at 2 AM?"        │
         │───────────────────────────────────→│
         │                                    │ 1. Check platform policies
         │                                    │ 2. Check app-defined policies
         │                                    │ 3. Check user-defined policies
         │  "No — time-of-day restriction"    │
         │←───────────────────────────────────│

The Policy Service evaluates all applicable policies in hierarchy order and returns a decision. Services never implement their own policy logic — they ask and obey.

Querying Service	Question	Policy Answer
Planner	“Which planning strategy for this order type?”	Use priority-first for urgent orders
Scheduler	“Can Robot A run at 2 AM?”	No — time-of-day restriction in effect
Execution Manager	“Contract failed, what now?”	Retry once, then reassign to nearest available
Planner	“Robot battery at 15%, continue?”	No — platform safety limit is 20%

Domain Policy Schemas

Applications register Domain Policy Schemas that teach the platform their domain vocabulary. This is what makes the AI Policy Agent domain-agnostic:

Platform provides:              App injects:
├─ Conversational engine        ├─ Domain ontology (entities, actions)
├─ Policy syntax understanding  ├─ Domain constraints
├─ Validation logic             ├─ Available strategies
└─ Common concepts              └─ Example policies / best practices
    (devices, zones, time)

Example schema (warehouse domain):

{
  "domain": "warehouse",
  "entities": ["order", "pick-task", "AMR", "rack", "zone"],
  "actions": ["pick", "place", "move", "charge", "wait"],
  "strategies": ["priority-first", "proximity-first", "load-balance"],
  "constraints": ["max-carry-weight", "zone-access-level"],
  "examples": [
    "Prioritize urgent orders over standard orders",
    "Never assign more than 3 tasks to a single AMR"
  ]
}

The schema is registered when an application is installed from the Marketplace. The AI Policy Agent loads the schema when an operator starts a policy conversation for that domain.

Pre-Activation Validation

No policy goes live without passing through the Policy Validator:

Check	Description	Example
Conflict detection	Two policies give contradictory answers for the same input	“Allow Zone A at night” vs “Deny Zone A after 10 PM”
Safety override	User/app policy attempts to weaken platform safety	Battery threshold set below platform minimum
Deadlock detection	Policies create circular blocking	A requires B complete first, B requires A complete first
Coverage gap	No policy covers a valid scenario	No failure recovery defined for timeout errors
Hierarchy violation	Lower-tier policy overrides higher-tier	User policy contradicts app-defined preset

The AI Policy Agent runs validation before proposing a policy to the operator. The Policy Service runs validation again before activation. This double validation ensures that conversationally-created policies are safe even if the Agent makes an error.

Conversational Policy Creation

The AI Policy Agent operates in two modes:

Creation mode — translating operator intent into formal policies:

Operator: "I want cleaning to stop during office hours on weekdays"
Agent:    "I understand. Let me create a policy:
           - Scope: All cleaning robots
           - Condition: Monday–Friday, 9 AM – 6 PM
           - Action: Suspend cleaning operations
           - Recovery: Resume at 6 PM, prioritize uncleaned areas

           I've validated this against your existing policies — no
           conflicts detected. Should I activate it?"
Operator: "Yes, but only for Floor 2"
Agent:    "Updated scope to Floor 2 only. Activating now."

Audit mode — explaining existing policies and simulating scenarios:

Operator: "What happens if a robot runs low on battery in Zone A?"
Agent:    "Based on your current policies:
           1. Platform safety: Robot must return to charging when battery
              drops below 20% (cannot be overridden)
           2. Your policy: Robots in Zone A should complete current task
              before returning to charge (applies above 20%)
           3. Result: Robot finishes the current pick, then navigates
              to the nearest charging station."

Consequences

Benefits

• Safety guarantees — platform policies cannot be weakened, regardless of what applications or operators define

• Domain flexibility — the same policy engine works for warehouses, cleaning, logistics, and any future domain via schemas

• No-code customization — operators tune behavior through conversation, not configuration files or code

• Auditable — every policy is versioned, every decision is logged, the AI Agent can explain any policy in plain language

• Conflict prevention — validation catches problems before they reach production

Trade-offs

• Schema design burden — application developers must design Domain Policy Schemas carefully; a poorly designed schema limits what operators can express

• Validation latency — complex policy sets with many interactions take longer to validate; this is acceptable for policy creation (infrequent) but the evaluation path (frequent, per-decision) must remain fast

• Agent accuracy — the AI Policy Agent may misinterpret ambiguous operator intent; the double validation (Agent + Policy Service) mitigates this, but operators must still review proposed policies

Design Decisions

• Policies are data, not code — policies are stored as structured definitions, not executable scripts. This makes them inspectable, validatable, and explainable.

• Services ask, not decide — Intelligence Plane services never implement their own policy logic. They query the Policy Service for every decision. This centralizes policy enforcement and prevents drift.

• App schemas are injected at install time — schemas are registered when an application is installed from the Marketplace, ensuring the platform’s policy infrastructure is ready before any operator attempts to create policies for that domain.

Examples

WES — Order Priority Policy

A warehouse operator wants urgent orders to be prioritized:

1. The WES application’s Domain Policy Schema defines order as an entity with priority as an attribute, and priority-first as a strategy

2. The operator tells the AI Policy Agent: “Urgent orders should always be picked before standard orders”

3. The Agent creates a policy: IF order.priority = "urgent" THEN strategy = priority-first

4. The Validator checks: no conflict with platform policies, no conflict with existing app-defined policies

5. The policy is activated

6. When the Planner asks “which strategy for this order?”, the Policy Service returns priority-first for urgent orders

ClearJanitor — Time-of-Day Restriction

A building operator wants cleaning to happen only at night:

1. The ClearJanitor schema defines cleaning-robot as an entity with time-window as a constraint

2. The operator says: “No cleaning between 8 AM and 7 PM on weekdays”

3. The Agent creates a scoped policy with the time condition

4. The Validator checks: this doesn’t conflict with the platform safety policy requiring minimum cleaning frequency (if one exists)

5. When the Scheduler asks “can this robot clean Floor 2 at 3 PM?”, the Policy Service returns “No — time-of-day restriction”