Skip to content
Feature Execution
FEAT-CORE-000: Feature Execution Constitutional Directive

FEAT-CORE-000: Feature Execution Constitutional Directive

Reference Number Version Effective Date Supersedes Authority Level
FEAT-CORE-000 1.1 2026-09-30 1.0 Constitutional. Subordinate to INV-CORE-000, INV-CORE-001, and INV-ARC-006.

I. Purpose

This document defines the mandatory execution contract for all Feature Execution (FEAT) units.

A FEAT is the only legal mechanism by which:

  • state is mutated
  • money is moved
  • identity is bound
  • cross-domain coordination occurs

Any behavior outside this contract is considered non-compliant.

This directive additionally governs lawful orchestration of constitutional economic policy evolution: each change is a new row in its owning domain’s table, carrying the instant from which it governs (DOM-CLASS-003 §V, §VII). (1.1, operator ruling 2026-09-30: there is no policy transition or activation step; the class-wide lineage tables that held them are retired.)

II. Definition of a FEAT

A FEAT is an atomic orchestration unit that:

  1. Resolves identity context
  2. Validates intent across domains
  3. Executes state mutations within a single transaction boundary
  4. Emits an auditable execution trace

A FEAT:

  • MAY call Domains (guards, queries, commands)
  • MUST NOT call another FEAT executor (no FEAT-to-FEAT execution; see §V.1)
  • MUST NOT be bypassed by routes, jobs, or scripts

Monetary FEATs that move funds MUST, inside their own single FEAT context, construct an intended ledger plan and resolve/apply it through the Ledger domain commands (build_intended_ledger_plan / resolve_intended_ledger_plan / apply_resolved_ledger_plan — plain domain functions, not FEAT executors). A money-moving FEAT does not execute a separate “FEAT-LED-000” / “FEAT-LED-001” (that would be forbidden FEAT-to-FEAT execution; see §V.1).

III. Core Execution Requirements

1. Context-First Execution (MANDATORY)

A FEAT MUST resolve:

  • user_id
  • seat_id
  • class_id

before any domain interaction occurs.

Failure Contract: If context cannot be resolved:

  • execution MUST abort
  • no state mutation is allowed
  • an audit event MUST be emitted via DOM-OPS

2. Single Transaction Boundary (MANDATORY)

A FEAT MUST execute within a single atomic transaction.

The transaction MUST include:

  • all ledger entries
  • all domain state mutations derived from the action
  • all correlation identifiers linking them
  • every economic policy row the action records

Failure Behavior:

  • partial writes are forbidden
  • any failure MUST trigger full rollback

3. Idempotency (MANDATORY)

Every FEAT MUST be safe to retry.

Requirements:

  • an idempotency_key MUST be accepted or generated.
  • duplicate executions MUST NOT produce duplicate effects.
  • Scope: Idempotency MUST apply to identity binding, entitlement creation, and obligation state transitions, in addition to ledger entries.
  • ledger duplication MUST be prevented at the database level.
  • replayed economic policy changes MUST NOT record a policy row twice.

4. Audit Logging & Correlation (MANDATORY)

Every FEAT execution MUST emit an audit record via DOM-OPS containing:

  • FEAT identifier
  • actor (user_id, seat_id, class_id)
  • correlation_id: A unique identifier that MUST be generated and propagated for all multi-step, linked, or reversible operations.
  • input payload (sanitized)
  • result (success/failure)
  • timestamp

Failure to log = non-compliant execution

IV. Domain Interaction Rules

1. Domain Isolation (MANDATORY)

Domains:

  • MUST NOT call other domains
  • MUST NOT orchestrate workflows
  • MUST NOT initiate ledger writes outside their scope

All cross-domain coordination MUST occur inside a FEAT.

This includes lawful orchestration of economic policy changes through their owning commands.

2. Validation vs Mutation Separation (MANDATORY)

Domains MAY:

  • validate conditions
  • return eligibility / constraint responses

Domains MUST NOT:

  • mutate state during validation
  • trigger side effects implicitly

Ordering Guarantee: A FEAT MUST NOT perform any state mutation until all validation phases (across all involved domains) complete successfully.

Example (Prohibited):

  • Store validation triggering overdraft fee before purchase success is guaranteed.

Correct Pattern:

  • FEAT performs validation → FEAT performs mutation explicitly.

3. Guard Pattern Standardization (MANDATORY)

To ensure consistent cross-domain enforcement, all “Domain Guards” MUST follow a standardized interface:

Pattern: DOM-[DOMAIN].check_[CONDITION](context_id) -> { allowed: bool, reason: enum, metadata: dict }

Requirements:

  • Guards MUST be read-only.
  • Guards MUST return a machine-readable reason code (Enum).
  • FEATs MUST handle both allowed: true and allowed: false outcomes explicitly.
  • Guards MUST NOT throw exceptions for business-level rejections; they must return allowed: false.

3. Ledger Authority (MANDATORY)

All money movement MUST be executed through DOM-LED.

No domain may:

  • create implicit financial effects
  • bypass ledger recording
  • simulate balance changes

V. FEAT Composition Rules

1. No FEAT-to-FEAT Execution

A FEAT executor MUST NOT invoke another FEAT executor — directly or indirectly, and regardless of correlation-ID equality. This holds for every FEAT; there is no Core-FEAT carve-out. The earlier “Core FEATs MAY be called by other FEATs” allowance (FEAT-PAY-POST, FEAT-IDEN-LOGIN, FEAT-LED-000) is removed — it is superseded by the higher-authority execution model:

  • INV-ARC-000 §VIII.2 — exactly one command path executes per request;
  • INV-ARC-021 §V.2 — the FEAT is the only construct permitted to compose logic across domains, within a single execution path;
  • INV-ARC-006 — all mutation occurs inside explicit domain commands.

Shared functionality is invoked through domain-level guards, queries, and commands (plain domain functions / services), never through another FEAT. For example, a money-moving FEAT composes the Ledger domain commands (resolve_intended_ledger_plan / apply_resolved_ledger_plan, which are plain domain functions, not FEAT executors) inside its own single context — it does not execute a “FEAT-LED-000”.

Enforcement: the runtime FEATContext guard rejects entering any FEAT context while another is active (regardless of feat_name/correlation), and a structural CI check forbids a FEAT module from importing another FEAT’s executor.

VI. Side-Effect Governance

1. Explicit Side Effects Only (MANDATORY)

No FEAT may trigger hidden or implicit side effects.

All side effects MUST be:

  • explicitly declared
  • executed within the transaction boundary
  • traceable via audit logs

Example (Prohibited):

  • Payroll implicitly mutating economic policy state

Correct Pattern:

  • FEAT emits event → separate FEAT handles rebalance
  • A change for a later boundary is recorded now as a row dated to that boundary; nothing activates it

2. Post-Execution Events (ALLOWED)

FEATs MAY emit events for downstream processing:

  • analytics
  • policy-governance analysis
  • notifications

These MUST:

  • be emitted ONLY AFTER a successful transaction commit.
  • not mutate core state within the originating transaction.
  • be idempotent and replay-safe.

VII. Identity Authority Rules

1. Seat as Execution Context (MANDATORY)

All FEAT execution MUST be scoped to a resolved seat_id.

No FEAT may operate using:

  • raw user_id alone
  • join_code as authority
  • global identity lookups

2. Binding Integrity (MANDATORY)

Identity binding operations MUST:

  • occur only within FEAT-IDEN-*
  • be atomic
  • not leak intermediate states

VIII. Prohibited Patterns

The following are explicitly forbidden:

  1. Route-level business logic that mutates multiple domains
  2. Domain calling another domain
  3. Ledger mutation during validation phase
  4. Partial state updates without ledger correlation
  5. Hidden entitlement creation without ledger trace (unless explicitly zero-value and declared)
  6. Context-less execution (no seat_id)
  7. Reconstruction of authoritative state from non-authoritative sources (e.g., using ledger as attendance truth)
  8. Direct mutation of constitutional economic policy state instead of appending a row to the owning table
  9. Hidden delayed economic mutation that is not a visible, effective-dated row
  10. Operational domains rewriting a policy row

IX. Compliance Requirements

All FEAT implementations MUST:

  • declare required context inputs
  • define transaction boundary scope
  • specify idempotency mechanism
  • emit audit logs
  • pass invariant checks post-execution
  • record economic governance changes as new rows of the owning table

CI SHOULD enforce:

  • no direct domain-to-domain calls
  • no route-level multi-domain mutation
  • presence of audit logging
  • presence of idempotency handling
  • prohibition against in-place mutation of an economic policy row

X. Execution Boundary Enforcement (MANDATORY)

All state mutation MUST originate from a FEAT.

The following are prohibited from performing direct mutations:

  • Routes (Flask handlers)
  • Background jobs
  • CLI scripts

These MUST invoke a FEAT instead to interact with domain state.

Constitutional economic policy evolution MUST occur through FEAT-orchestrated execution of the owning domain’s command.

Direct mutation of an economic policy row outside FEAT execution is prohibited.

To ensure compliance, the implementation SHOULD utilize:

  • Context Decorators: @requires_feat_context on domain mutation methods.
  • DB Assertions: A database wrapper that asserts a valid FEAT_EXECUTION_CONTEXT is present before committing.
  • Linting Rules: CI checks to detect db.session.add/commit calls outside the /app/features/ directory.

XI. Relationship to Other Documents

  • INV-CORE-* defines system invariants (higher authority)
  • DOM-* defines domain rules and data ownership
  • FEAT-* defines concrete execution units governed by this directive
  • MAP-* provides non-normative mappings and guidance

XII. Dependencies

  • docs/INVARIANT/CORE/INV-CORE-000_CORE_INVARIANTS.md
  • docs/INVARIANT/CORE/INV-CORE-001_CAPABILITY_BASED_ARCHITECTURE_AND_AUTHORITY_MODEL.md
  • docs/INVARIANT/ARCHITECTURE/INV-ARC-006_COMMAND_BOUNDARY_FOR_MUTATION.md
Edit canonical source on GitHub

Last updated: 2026-10-01

FEAT-CLASS-008: Acknowledge the Unpaid-Work NoticeFEAT-ECON-001: Economic Rebalance Execution