254 lines
4.7 KiB
Markdown
254 lines
4.7 KiB
Markdown
|
# Primitive Ops vs Pluggable Ops
|
|||
|
|
|
|||
|
|
This section defines the execution boundary between deterministic kernel semantics and extensible domain execution.
|
|||
|
|
|
|||
|
|
It preserves:
|
|||
|
|
|
|||
|
|
* Kernel determinism
|
|||
|
|
* Store-neutral traceability
|
|||
|
|
* Backend substitutability
|
|||
|
|
* Observational equivalence
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 1. Terminology
|
|||
|
|
|
|||
|
|
## 1.1 Kernel / Primitive Op
|
|||
|
|
|
|||
|
|
A **Kernel Op** (Primitive Op) is an operation defined in:
|
|||
|
|
|
|||
|
|
`OPREG/PEL1-KERNEL`
|
|||
|
|
|
|||
|
|
It is part of the `PEL/1-CORE` contract.
|
|||
|
|
|
|||
|
|
Kernel ops define fixed, deterministic semantics and are considered part of Amduat’s invariant semantic core.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1.2 Pluggable Op
|
|||
|
|
|
|||
|
|
A **Pluggable Op** is an operation defined outside `OPREG/PEL1-KERNEL`.
|
|||
|
|
|
|||
|
|
It is not part of `PEL/1-CORE`.
|
|||
|
|
|
|||
|
|
Its execution semantics:
|
|||
|
|
|
|||
|
|
* Are versioned independently
|
|||
|
|
* May be effectful
|
|||
|
|
* Are governed by profile or deployment policy
|
|||
|
|
* Must emit execution artifacts for traceability
|
|||
|
|
|
|||
|
|
Pluggable ops extend behavior without extending the kernel.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 2. Kernel / Primitive Ops
|
|||
|
|
|
|||
|
|
## 2.1 Properties
|
|||
|
|
|
|||
|
|
Kernel ops:
|
|||
|
|
|
|||
|
|
* Are defined in `OPREG/PEL1-KERNEL`
|
|||
|
|
* Are pure and deterministic
|
|||
|
|
* Have no side effects
|
|||
|
|
* Depend only on explicit inputs
|
|||
|
|
* Produce canonical artifacts
|
|||
|
|
* Have stable semantics governed by spec revision
|
|||
|
|
|
|||
|
|
Kernel ops are portable across all backend tiers.
|
|||
|
|
|
|||
|
|
They cannot:
|
|||
|
|
|
|||
|
|
* Access external systems
|
|||
|
|
* Read hidden state
|
|||
|
|
* Depend on environmental configuration
|
|||
|
|
* Produce nondeterministic outputs
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2.2 Examples
|
|||
|
|
|
|||
|
|
* `bytes.concat`
|
|||
|
|
* `bytes.slice`
|
|||
|
|
* `hash.asl1_256`
|
|||
|
|
|
|||
|
|
These operations:
|
|||
|
|
|
|||
|
|
* Operate solely on canonical encoded inputs
|
|||
|
|
* Produce deterministic outputs
|
|||
|
|
* Are observationally equivalent across implementations
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 3. Pluggable Ops
|
|||
|
|
|
|||
|
|
Pluggable ops enable domain-specific execution without extending the kernel.
|
|||
|
|
|
|||
|
|
They may:
|
|||
|
|
|
|||
|
|
* Invoke LLMs
|
|||
|
|
* Execute SSH commands
|
|||
|
|
* Configure infrastructure
|
|||
|
|
* Perform device operations
|
|||
|
|
* Call external APIs
|
|||
|
|
|
|||
|
|
They are not part of the core semantic contract.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3.1 Properties
|
|||
|
|
|
|||
|
|
Pluggable ops:
|
|||
|
|
|
|||
|
|
* Are defined in external registries
|
|||
|
|
* May be effectful
|
|||
|
|
* May interact with external systems
|
|||
|
|
* May be nondeterministic
|
|||
|
|
* Must produce execution artifacts
|
|||
|
|
* Must remain observationally separable from kernel semantics
|
|||
|
|
|
|||
|
|
They extend behavior while preserving traceability.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 4. Execution Artifact Model
|
|||
|
|
|
|||
|
|
Every pluggable op MUST emit execution artifacts to ASL.
|
|||
|
|
|
|||
|
|
These artifacts preserve determinism at the semantic layer, even if the effect itself is nondeterministic.
|
|||
|
|
|
|||
|
|
## 4.1 Required Artifacts
|
|||
|
|
|
|||
|
|
At minimum:
|
|||
|
|
|
|||
|
|
### 1. ExecutionIntent
|
|||
|
|
|
|||
|
|
Declares:
|
|||
|
|
|
|||
|
|
* Target
|
|||
|
|
* Parameters
|
|||
|
|
* Configuration
|
|||
|
|
* Version of pluggable op
|
|||
|
|
|
|||
|
|
Represents the desired action.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 2. ExecutionReceipt
|
|||
|
|
|
|||
|
|
Confirms:
|
|||
|
|
|
|||
|
|
* Action dispatch
|
|||
|
|
* Acceptance by executor
|
|||
|
|
* Execution attempt metadata
|
|||
|
|
|
|||
|
|
Represents the attempt.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 3. ExecutionOutput
|
|||
|
|
|
|||
|
|
Captures:
|
|||
|
|
|
|||
|
|
* Stdout/stderr
|
|||
|
|
* Returned data
|
|||
|
|
* Produced artifacts
|
|||
|
|
* Exit codes
|
|||
|
|
|
|||
|
|
Represents the immediate result.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 4. ExecutionObservation (Recommended)
|
|||
|
|
|
|||
|
|
Captures:
|
|||
|
|
|
|||
|
|
* Observed external state
|
|||
|
|
* Post-condition checks
|
|||
|
|
* Environment validation
|
|||
|
|
|
|||
|
|
Represents the verified outcome.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
All execution artifacts:
|
|||
|
|
|
|||
|
|
* Are canonical ASL artifacts
|
|||
|
|
* Are immutable
|
|||
|
|
* Derive identity via `ENC/ASL1-CORE` + `ASL/1-CORE` + `HASH/ASL1`
|
|||
|
|
* Participate in TGK projection
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 5. Traceability Requirements
|
|||
|
|
|
|||
|
|
All pluggable ops MUST be traceable in TGK by linking:
|
|||
|
|
|
|||
|
|
* `ExecutionIntent → ExecutionReceipt`
|
|||
|
|
* `ExecutionReceipt → ExecutionOutput`
|
|||
|
|
* Optional: `ExecutionOutput → ExecutionObservation`
|
|||
|
|
|
|||
|
|
These links are created via EdgeArtifacts written to ASL.
|
|||
|
|
|
|||
|
|
This ensures:
|
|||
|
|
|
|||
|
|
* Deterministic graph projection
|
|||
|
|
* Provenance recoverability
|
|||
|
|
* Replay safety
|
|||
|
|
* Auditability
|
|||
|
|
|
|||
|
|
Even if external execution is nondeterministic, the trace is deterministic.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 6. Governance Boundary
|
|||
|
|
|
|||
|
|
The boundary between kernel and pluggable ops is strict.
|
|||
|
|
|
|||
|
|
## 6.1 Kernel
|
|||
|
|
|
|||
|
|
* Small
|
|||
|
|
* Deterministic
|
|||
|
|
* Slow-moving
|
|||
|
|
* Versioned with PEL core
|
|||
|
|
* Subject to formal governance
|
|||
|
|
|
|||
|
|
## 6.2 Pluggable
|
|||
|
|
|
|||
|
|
* Extensible
|
|||
|
|
* Fast-moving
|
|||
|
|
* Policy-scoped
|
|||
|
|
* Profile-scoped
|
|||
|
|
* May be deployment-specific
|
|||
|
|
|
|||
|
|
No pluggable op may redefine kernel semantics.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 7. Interaction with Backend Plug-in Model
|
|||
|
|
|
|||
|
|
This execution model aligns with the No Semantic Drift Rule:
|
|||
|
|
|
|||
|
|
* Kernel ops are invariant across all backends.
|
|||
|
|
* Pluggable ops must emit artifacts.
|
|||
|
|
* Backends must treat execution artifacts as ordinary ASL artifacts.
|
|||
|
|
* TGK projection must remain deterministic.
|
|||
|
|
|
|||
|
|
Backend-specific optimizations must remain observationally equivalent to the artifact graph defined by execution artifacts.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 8. Design Outcome
|
|||
|
|
|
|||
|
|
This separation:
|
|||
|
|
|
|||
|
|
* Preserves deterministic core semantics
|
|||
|
|
* Enables real-world execution
|
|||
|
|
* Prevents semantic leakage into infrastructure
|
|||
|
|
* Maintains backend substitutability
|
|||
|
|
* Ensures enterprise-grade auditability
|
|||
|
|
* Supports edge and embedded deployments
|
|||
|
|
|
|||
|
|
Primitive ops define what Amduat *is*.
|
|||
|
|
Pluggable ops define what Amduat *does*.
|