HIF / Documentation / Architecture

HIF Interaction Model

1. Purpose

The interaction model translates the Constitution into architectural concepts. It does not prescribe a particular framework or programming language.

Normative chain:

human intention
→ semantic command
→ validation of preconditions and authority
→ state transition
→ event and history
→ representation of the outcome

A DOM event, pointer gesture or keyboard shortcut is not a product command. It is only one means of expressing an intention.

2. Core entities

2.1. Actor

A participant capable of initiating an action:

person;
system;
another person;
external service;
automation;
AI agent.

An Actor has an identity, role, permissions and context.

2.2. Object

A domain entity with a stable identity:

file;
project;
window;
application;
build;
release;
user;
device;
document.

An Object is not equivalent to its representation.

2.3. View

A representation of one or more Objects:

row;
card;
window;
tab;
icon;
page;
notification;
voice response.

Several Views MAY refer to one Object. Closing a View does not entail deleting the Object.

2.4. Command

An intentional action with a defined contract:

type Command = {
  id: string;
  actor: ActorRef;
  target: ObjectRef;
  parameters: unknown;
  preconditions: readonly Condition[];
  requiredPermissions: readonly Permission[];
  effect: Effect;
  reversibility: "reversible" | "compensatable" | "irreversible";
  risk: "low" | "moderate" | "high" | "critical";
};

The concrete implementation MAY vary, but the semantic fields should be available to architecture and verification.

2.5. Event

A fact that occurred within the system. A Command expresses intention; an Event records the outcome.

release.publish requested
release.publish accepted
release.published

A Command MAY fail and produce a failure Event.

2.6. State

A set of facts that hold at a particular moment. State should not be inferred from an arbitrary combination of CSS classes.

2.7. Policy

A rule that determines whether an action is permissible:

permission;
data retention;
movement;
removal;
approval;
validation;
environment capability.

2.8. Context

Conditions of use:

device and viewport;
input methods;
network and performance;
locale;
accessibility preferences;
role and authority;
current task;
physical and social environment.

3. Component states

The minimum set of distinguishable axes is:

availability: enabled | disabled | unavailable
interaction: idle | hover | focused | active
selection: unselected | selected | mixed
disclosure: collapsed | expanded
operation: ready | pending | success | error | cancelled
validation: unknown | valid | invalid | warning
visibility: visible | hidden | offscreen

Axes should not be conflated without a domain-specific reason. For example:

focused does not mean selected;
disabled does not mean hidden;
error does not mean invalid user input;
pending does not mean success.

4. Command lifecycle

4.1. Formation

The interface gathers the intention, target and parameters. Material parameters should be inspectable before execution.

4.2. Validation

The system checks:

whether the target exists;
whether the State is current;
permissions;
parameter validity;
conflicts;
whether approval is required;
dependency availability.

4.3. Acceptance

Once a Command has been accepted, the interface immediately indicates that the action has been registered. Acceptance does not necessarily mean completion.

4.4. Execution

For a long-running operation, the interface presents status, progress, the ability to cancel and the consequences of leaving the page.

4.5. Completion

The outcome is associated with the original task and target. The system distinguishes success, partial success, cancellation and failure.

4.6. Recovery

When an error occurs, the system preserves everything that can safely be preserved and offers the next valid Command.

5. Input bindings

The product defines semantic Commands independently of input:

pointer click ─────┐
Enter ─────────────┼── object.open
voice "open" ──────┤
automation API ────┘

The environment profile defines bindings for:

pointer;
keyboard;
touch;
pen;
switch control;
voice;
remote control;
automation.

Bindings may differ. The effect and safety requirements remain the same.

6. Focus

Focus is a system resource indicating which element receives keyboard or assistive-technology input.

6.1. Rules

At any moment, there is no more than one primary focus point within a single context.
Focus should be visible.
Focus order should correspond to structure and task.
Opening a dialog moves focus inside it.
Closing a dialog returns focus to the initiator or another safe point.
A disabled control should not create a focus trap.
A composite widget manages internal focus according to a consistent grammar.

6.2. Focus and selection

Selection identifies a chosen Object. Focus identifies the recipient of input. They can coincide, but they are not the same entity.

HIF permits several models:

linear;
hierarchical;
spatial;
search-first;
command-first;
workspace;
document history;
graph;
conversational.

The product MUST define:

the current position;
the parent or source context;
the transition mechanism;
the return mechanism;
deep-link behaviour;
State preservation on return.

Models may be combined provided that their boundaries remain distinguishable.

8. Layers and modes

Typical layers are:

content
navigation
floating surface
overlay
system
modal
critical

Each layer defines:

z-order;
focus ownership;
dismissal method;
scroll ownership;
effect on lower layers;
accessibility exposure.

A Mode SHOULD be used only when the same input genuinely changes meaning for a limited period. The active Mode should be perceptible and provide a means of exit.

9. Undo and compensation

9.1. Reversible

The system can restore the previous State without loss of meaning.

9.2. Compensatable

A fact cannot be undone, but a compensating action is available. For example, a published release cannot be made “never to have been published”, but it can be withdrawn.

9.3. Irreversible

Recovery is impossible or cannot be guaranteed. Such a Command requires:

a clear target;
the scale of the consequences;
an explanation of irreversibility;
enhanced verification when risk is high.

Confirmation should not be used for every action: persistent confirmation dialogs train people to confirm automatically.

10. Feedback timing

These time ranges are working guidelines, not universal laws:

at approximately 100 ms or less, a response is perceived as immediate;
at approximately 1 s or less, clear acknowledgement is required, but the flow of thought is generally preserved;
a longer operation requires a progress state;
a prolonged operation SHOULD allow other work to continue.

The system should not simulate completion merely to create an impression of speed.

11. Errors

An error is represented structurally:

type InteractionError = {
  kind:
    | "invalid-input"
    | "permission"
    | "conflict"
    | "dependency"
    | "system"
    | "policy";
  target?: ObjectRef;
  recoverable: boolean;
  nextCommands: readonly CommandRef[];
  technicalReference?: string;
};

User-facing wording and technical detail are separated. A technical reference should support investigation and audit without disclosing secrets.

12. Automation and AI

Agentic interaction uses the same Command model.

request
→ proposed plan
→ scoped permissions
→ preview
→ approval where required
→ command execution
→ observable events
→ outcome and recovery

AI output is not a Command until it has passed schema, authority and Policy checks.

The interface MUST distinguish:

a textual recommendation;
a prepared draft;
a proposed plan;
an action in progress;
a confirmed outcome.

13. Collaboration

For a multi-user interface, the following are defined:

the Actor responsible for each change;
State currency;
optimistic or pessimistic locking;
conflict and merge behaviour;
presence;
history;
viewing and modification permissions;
private and shared Views.

Presence should not create the false impression that another person is viewing data when the system indicates only availability or connection.

14. Traceability

Each material function SHOULD have a traceable chain:

user goal
→ task
→ object
→ command
→ state transition
→ event
→ view
→ automated test
→ evaluation task

A break in the chain means that the function either lacks a product rationale or cannot be verified reliably.