Absolutely. Here’s a rough outline you can refine into a real internal spec.
# AIS Identity Model v0.1 — Rough Outline
## 1. Purpose
The AIS Identity Model defines how the platform names, distinguishes, and tracks:
* machines / nodes
* workloads / managed applications
* individual runtime generations
* the component currently authorized to report or mutate state
Its purpose is to prevent ambiguity as AIS grows from a simple runner pattern into a multi-application system with orchestration, recovery, monitoring, and policy enforcement.
This model exists so the system can answer, clearly and consistently:
* **where** is this happening?
* **what** application/workload are we talking about?
* **which specific run** are we talking about?
* **who is currently allowed to speak for it?**
---
## 2. Why This Exists
AIS did not begin with a formal identity model. Identity emerged as the system grew more layered and more modular.
Earlier implementations often allowed a single field like `app_id` or a shared state file to carry too much meaning at once. As more components were introduced, this caused identity to blur across:
* configuration
* runtime state
* process ownership
* project naming
* recovery semantics
* machine registration
The result is that the system now needs a deliberate model so that identity is no longer implied by whichever struct or file happens to be in scope.
---
## 3. Core Design Goals
The identity model should support the following goals:
### 3.1 Stable Naming
The same workload should be recognizable across rebuilds, restarts, crashes, and reporting.
### 3.2 Scoped Identity
Different kinds of things should have different kinds of identifiers.
A node is not a workload.
A workload is not a runtime.
A runtime is not a control authority.
### 3.3 Recovery Safety
If an intermediate crashes or goes stale, other parts of AIS must still be able to refer to that runtime and update its recorded state safely.
### 3.4 Modular Ownership
Cheap, disposable intermediate applications should still be able to publish and own state while alive, without forcing all higher systems to share a mutable flat file.
### 3.5 Trust and Security
Because AIS may execute untrusted or unknown code in constrained environments, identities must support secure local coordination and work alongside encryption, verification, and process separation.
---
## 4. Identity Domains
The AIS model should distinguish four primary identity domains.
## 4.1 Node Identity
### Definition
A durable identifier assigned to a node, host, or AIS manager installation.
### Purpose
Used to identify the machine or system boundary that owns local resources and runs intermediates.
### Characteristics
* persistent across restarts
* durable on disk
* cryptographically verifiable if needed
* used for registration and trust
* not tied to any one workload
### Answers
* Which node is this?
* Which host owns this workload execution?
* Which machine produced this report?
### Notes
This maps closely to your current persisted identifier primitive.
---
## 4.2 Workload Identity
### Definition
A stable identifier for a managed application, project, or deployment target.
### Purpose
Represents the logical application slot AIS is managing, regardless of which specific process generation is currently running.
### Characteristics
* stable across rebuilds and restarts
* may be derived from Git identity, config, declared name, or a generated internal ID
* used for policy, billing, routing, and historical tracking
* should not change just because the process was restarted
### Answers
* Which app/service/project are we talking about?
* Is this the same managed workload as before?
### Notes
This is what a Git-derived project ID is often approximating today.
---
## 4.3 Runtime Identity
### Definition
An ephemeral identifier for one specific execution generation of a workload.
### Purpose
Represents one concrete run of the intermediate + client application lifecycle.
### Characteristics
* changes on rebuild/restart/re-initialization
* scoped under a workload
* used to correlate:
* PID
* metrics
* logs
* heartbeats
* current snapshot data
* allows stale updates from prior runs to be rejected
### Answers
* Which specific run is this?
* Does this update belong to the current generation or an old one?
### Notes
This is the biggest missing identity primitive in the current design.
---
## 4.4 Authority Identity
### Definition
A bounded identity for the component currently authorized to publish or mutate canonical state for a runtime.
### Purpose
Allows AIS to distinguish between:
* the intermediate while healthy
* the lifecycle manager during recovery/takeover
* a future dedicated state service or recovery process
### Characteristics
* ephemeral
* scoped to a runtime or runtime generation
* transferable under explicit rules
* used to prevent split-brain state updates
### Answers
* Who is allowed to speak for this runtime right now?
* Is this update authoritative?
### Notes
This is less about naming the app and more about naming the current state authority.
---
## 5. Things That Are Not Identity
To keep the model clean, AIS should explicitly separate identity from adjacent concerns.
## 5.1 Configuration is not Identity
Configuration describes how a workload should run.
Examples:
* memory limit
* environment
* ports
* Git branch
* runtime flags
* logging settings
These may help derive or bind identity, but they are not identity themselves.
## 5.2 Runtime State is not Identity
State describes what is currently true.
Examples:
* running/stopped
* healthy/unhealthy
* current PID
* current memory usage
* last heartbeat
* restart count
These are attached to a runtime identity, but they are not identity.
## 5.3 Snapshot is not Identity
A snapshot is a serialized view of state, config, and metadata at a moment in time.
It may contain identity fields, but the snapshot itself is not the identity.
## 5.4 Events are not Identity
Events record what happened and who said it happened.
They refer to identities, but do not define them.
---
## 6. Proposed Relationship Model
AIS should think about managed application data in the following hierarchy:
### Node
The machine or manager installation.
### Workload
The logical app/service definition on that node.
### Runtime
A specific execution generation of that workload.
### Authority
The actor currently allowed to publish canonical state for that runtime.
This gives a chain like:
`node -> workload -> runtime -> authority`
That relationship should be explicit in internal messages and stored records.
---
## 7. Identity Invariants
These are the rules the system should aim to preserve.
## 7.1 A node identity must outlive any workload runtime
Node identity is durable and should not rotate every time workloads change.
## 7.2 A workload identity must remain stable across runtime generations
Restarting or rebuilding a managed app should not create a brand-new workload identity unless the workload itself is truly new.
## 7.3 A runtime identity must be unique per generation
A runtime generation should never reuse the same runtime ID as a previous generation of the same workload.
## 7.4 Only one authority may be canonical for a runtime at a time
AIS should not allow multiple components to publish conflicting canonical state for the same active runtime generation.
## 7.5 A stale authority must be rejectable
If an intermediate dies or loses authority, late updates from that stale authority must not overwrite current truth.
---
## 8. Operational Semantics
## 8.1 Normal Operation
When the intermediate is healthy:
* the intermediate publishes state for its runtime
* the lifecycle manager supervises
* the API/monitoring layer reads or relays
In this condition, the intermediate is the authority.
## 8.2 Crash / Loss of Heartbeat
When the intermediate becomes stale:
* the runtime remains identifiable
* the lifecycle manager or state service may take authority
* the system may mark the runtime terminated, stale, lost, or rebuilding
* a new runtime generation may later be created under the same workload
## 8.3 Rebuild / Restart
When a rebuild happens:
* workload identity remains the same
* runtime identity changes
* authority identity changes
* state history may continue under the same workload lineage
---
## 9. Rough Field Model
Not final naming, just rough structure.
## 9.1 Node Identity Fields
* `node_id`
* `node_signature` or verification material
* `node_created_at`
* `node_class` or role
## 9.2 Workload Identity Fields
* `workload_id`
* `workload_name`
* `project_id`
* `source_id` or Git-derived ID
* `node_id`
## 9.3 Runtime Identity Fields
* `runtime_id`
* `workload_id`
* `generation_number` or `generation_id`
* `started_at`
* `ended_at`
## 9.4 Authority Identity Fields
* `authority_id`
* `authority_kind`
* `runtime_id`
* `granted_at`
* `expires_at` or heartbeat deadline
---
## 10. Suggested Terminology Cleanup
This is one of the big practical wins.
### Prefer
* `node_id`
* `workload_id`
* `runtime_id`
* `authority_id`
### Avoid overloading
* `app_id`
Because `app_id` currently risks meaning:
* app name
* project identity
* runtime generation
* registration ID
* current process identity
That ambiguity should be reduced.
---
## 11. Interaction With State Tracking
The identity model should guide the state system, not be embedded inside a single shared file by accident.
### Recommended principle
State should always be attached to:
* a workload identity
* a runtime identity
* a reporting authority
This lets AIS distinguish:
* “the workload exists”
* “this generation is dead”
* “this actor marked it terminated”
* “a new generation has replaced it”
That is much safer than just “whatever the latest state file says.”
---
## 12. Interaction With Security Model
Because AIS may run untrusted code, the identity model should support a trusted control plane.
This implies:
* identities used by trusted AIS components should be distinct from anything exposed to untrusted workloads
* local communications should bind updates to a known actor
* persisted identity/state records should support encrypted at-rest storage where required
* authority should not be inferred merely from file access
In other words, “can touch a file” should not mean “is allowed to define truth.”
---
## 13. Open Questions to Refine Later
These are the parts worth iterating on next.
### 13.1 How is workload identity generated?
We keep the git id we derive but we losen the truncate from 8 to 12 or 20 chars to give a more uuid vibe and reduce collisions
### 13.2 Should runtime identity be random, monotonic, or both?
The runtime id can be constructed in a hybrid approach.
we can take a epoch timestamp, a shortend workload id, and a random little hex string at the end so I can do cheap and quick searches later
### 13.3 Is authority identity separate from runtime identity?
derived from runtime session data.
### 13.4 Can one workload have multiple active runtimes?
NO
### 13.5 Which component is the long-term state authority?
A soon to be build state service
---
## 14. Proposed Next Step
The next pass should probably turn this outline into 3 tighter sections:
### A. Definitions
Clear one-paragraph definitions for each identity domain.
### B. Invariants and rules
The non-negotiable behaviors AIS should preserve.
### C. Concrete implementation mapping
How these identities appear in:
* Rust structs
* socket messages
* DB records
* state snapshots
* log/event records
---
Here’s the shortest version of the model:
**Node identity** says where.
**Workload identity** says what app.
**Runtime identity** says which run.
**Authority identity** says who is allowed to speak for it.
That’s the center of the whole thing.
On the next pass, I’d tighten this into something more spec-like and start mapping it onto your current Rust types.